Exceptions and Errors

Relevant source files

The following files were used as context for generating this wiki page:

• src/Exceptions/ErrorException.php
• src/Exceptions/MissingAttributeException.php
• src/Exceptions/TransporterException.php
• src/Exceptions/UnserializableResponse.php
• src/Exceptions/WebhookSignatureVerificationException.php
• src/WebhookSignature.php
• tests/Transporters/HttpTransporter.php
• tests/ValueObjects/Transporter/Payload.php

The Resend PHP library implements a structured error handling system using custom exceptions to manage API failures, network issues, and data integrity problems. These exceptions allow developers to distinguish between client-side validation errors, server-side API errors, and transport-level interruptions.

Exception Architecture

The library extends the base PHP Exception class to create a specialized hierarchy for different error scenarios.

The diagram shows the relationship between the base PHP Exception class and the specialized exceptions provided by the SDK.
Sources: src/Exceptions/ErrorException.php:7, src/Exceptions/TransporterException.php, src/Exceptions/UnserializableResponse.php, src/Exceptions/WebhookSignatureVerificationException.php

Core Exception Types

ErrorException

ErrorException handles structured error responses returned by the Resend API. When the API returns a non-success HTTP status code with a JSON body, the HttpTransporter parses the response and throws this exception. It encapsulates the error message, type, and code provided by the server.

Method	Return Type	Description
getErrorMessage()	string	Returns the human-readable error message.
getErrorType()	string	Returns the machine-readable error type (e.g., missing_required_field).
getErrorCode()	int	Returns the HTTP status code or internal error code.

Sources: src/Exceptions/ErrorException.php:12-38, tests/Transporters/HttpTransporter.php:157-164

TransporterException

TransporterException wraps errors that occur during the HTTP request process before a response is received from the API. This typically includes connection timeouts, DNS resolution failures, or other network-level issues. It often contains the original GuzzleHttp\Exception\ConnectException as a previous exception.

Sources: src/Exceptions/TransporterException.php, tests/Transporters/HttpTransporter.php:87-100

UnserializableResponse

UnserializableResponse occurs when the API returns a response that the library cannot process. This happens if:

• The response body is empty when JSON is expected.
• The Content-Type header is not application/json (e.g., text/plain or text/html).
• The JSON body contains syntax errors.

Sources: src/Exceptions/UnserializableResponse.php, tests/Transporters/HttpTransporter.php:73-85, tests/Transporters/HttpTransporter.php:173-184

Webhook Security Errors

The WebhookSignatureVerificationException manages failures during the verification of incoming webhook requests. The WebhookSignature class validates signatures to ensure requests originate from Resend.

The flowchart illustrates the sequence of validation checks performed during webhook signature verification.
Sources: src/WebhookSignature.php:11-53

Validation Failures

Verification fails under the following conditions:

• Missing Headers: The request lacks svix-id, svix-timestamp, or svix-signature.
• Invalid Timestamp: The timestamp is not numeric or falls outside the allowed 300-second tolerance (too old or too new).
• Signature Mismatch: None of the provided signatures in the svix-signature header match the locally computed HMAC-SHA256 hash.

Sources: src/WebhookSignature.php:18-20, src/WebhookSignature.php:51-53, src/WebhookSignature.php:97-111

Request Validation Errors

The library uses standard PHP exceptions for client-side data validation. For example, Payload::get() throws an InvalidArgumentException if a resource ID is an empty string.

// Example of client-side validation in Payload.php
if (empty($id)) {
    throw new InvalidArgumentException("The {$resource} ID must be a non-empty string.");
}

Sources: tests/ValueObjects/Transporter/Payload.php:119-121

Handling Errors in HttpTransporter

The HttpTransporter acts as the central point for mapping raw HTTP responses to specific exceptions.

Scenario	Resulting Action
HTTP 4xx/5xx with JSON body	Throws ErrorException
HTTP 2xx with non-JSON Content-Type	Throws UnserializableResponse
Malformed JSON body	Throws UnserializableResponse
Network/Connection Failure	Throws TransporterException

Sources: tests/Transporters/HttpTransporter.php:73-184

The structured nature of these exceptions ensures that applications can implement granular error handling based on the specific type of failure encountered during API interactions.