Exception and Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/java/com/resend/core/exception/ResendException.java
- src/test/java/com/resend/services/topics/TopicsTest.java
- src/test/java/com/resend/services/domains/DomainsTest.java
- src/test/java/com/resend/services/automations/AutomationsTest.java
- src/test/java/com/resend/services/webhooks/WebhooksTest.java
- src/main/java/com/resend/services/templates/Templates.java
The Resend Java SDK handles errors through a centralized exception system. The ResendException class manages API-related errors by capturing HTTP status codes and parsing JSON response bodies to provide detailed error information to the developer.
Sources: src/main/java/com/resend/core/exception/ResendException.java:1-12
ResendException Class Structure
ResendException extends the standard Java Exception class. It encapsulates specific metadata returned by the Resend API during failed requests.
Key Data Fields
| Field | Type | Description |
|---|---|---|
statusCode | Integer | The HTTP status code of the response (e.g., 422, 404, 401). |
errorName | String | The specific error type returned by the API (e.g., "validation_error"). |
responseBody | String | The raw JSON string returned by the server. |
Sources: src/main/java/com/resend/core/exception/ResendException.java:13-30
Exception Flow Architecture
The following diagram illustrates how an API error response is transformed into a ResendException.
The SDK captures the raw response and extracts internal error details to populate the exception object.
Sources: src/main/java/com/resend/core/exception/ResendException.java:68-115
Error Parsing Logic
The exception class includes static methods to extract information from JSON response bodies. If the body is not valid JSON or lacks expected fields, the logic provides fallbacks.
- Message Parsing: The
parseMessagemethod attempts to find a "message" field in the JSON. If it fails or the body is empty, it returns "Unknown error" or the raw body. - Error Name Parsing: The
parseErrorNamemethod searches for a "name" field (such asvalidation_errorornot_found). It returnsnullif the field is missing.
Sources: src/main/java/com/resend/core/exception/ResendException.java:82-115
Common Error Scenarios
Service modules across the SDK throw ResendException when API requirements are not met. The following table summarizes common error triggers observed in tests.
| Status Code | Error Name | Scenario Example |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key during domain listing. |
| 404 | not_found | Attempting to retrieve a domain or segment that does not exist. |
| 422 | validation_error | Providing an invalid email or domain during creation. |
| 500 | internal_server_error | Server-side failures during usage retrieval. |
Sources: src/test/java/com/resend/services/domains/DomainsTest.java:101-182, src/test/java/com/resend/services/usage/UsageTest.java:101-110, src/test/java/com/resend/services/topics/TopicsTest.java:80-89
Sequence of an Error Call
Each service method (e.g., create, get, remove) is declared to throw ResendException, requiring the user to handle potential failures.
Sources: src/main/java/com/resend/services/templates/Templates.java:44-55, src/test/java/com/resend/services/automations/AutomationsTest.java:114-125
Webhook Verification Errors
The Webhooks service provides specialized error handling for signature verification. Unlike standard API errors, these are triggered locally during the verification process.
- 401 Unauthorized: Thrown when signature verification fails, indicating the payload may have been tampered with or the secret is incorrect.
- 400 Bad Request: Thrown if the
svix-timestampis outside the 5-minute tolerance window, the payload is null, or the secret is empty.
Sources: src/test/java/com/resend/services/webhooks/WebhooksTest.java:232-300
Implementation Example
Users handle errors by catching ResendException and inspecting its properties.
try {
CreateEmailResponse data = resend.emails().send(params);
System.out.println(data.getId());
} catch (ResendException e) {
// Access HTTP status code
Integer status = e.getStatusCode();
// Access API error name (e.g. "validation_error")
String name = e.getErrorName();
e.printStackTrace();
}
Sources: README.md:65-71, src/main/java/com/resend/core/exception/ResendException.java:120-135
Summary
The exception system provides a unified way to interpret failures. By parsing the JSON response and capturing the HTTP status, ResendException allows developers to programmatically react to validation errors, authorization issues, and server-side problems.