Relevant source files

The following files were used as context for generating this wiki page: - [lib/resend/errors.rb](https://github.com/resend/resend-ruby/blob/main/lib/resend/errors.rb) - [lib/resend/request.rb](https://github.com/resend/resend-ruby/blob/main/lib/resend/request.rb) - [spec/request_spec.rb](https://github.com/resend/resend-ruby/blob/main/spec/request_spec.rb) - [CHANGELOG.md](https://github.com/resend/resend-ruby/blob/main/CHANGELOG.md) - [spec/contacts/topics_spec.rb](https://github.com/resend/resend-ruby/blob/main/spec/contacts/topics_spec.rb) - [spec/contacts_spec.rb](https://github.com/resend/resend-ruby/blob/main/spec/contacts_spec.rb) - [spec/webhooks_spec.rb](https://github.com/resend/resend-ruby/blob/main/spec/webhooks_spec.rb)

# Error Handling Error handling in the Resend Ruby SDK is designed to provide clear, actionable feedback when API requests fail or when invalid arguments are passed to SDK methods. The system categorizes errors into two primary types: technical/API-level errors (derived from HTTP responses) and client-side validation errors (standard Ruby exceptions). The SDK utilizes a centralized error handling logic within the `Resend::Request` class, which maps HTTP status codes to specific exception classes defined in the `Resend::Error` module. This ensures consistent error reporting across all API modules, including Emails, Contacts, and Templates. Sources: [lib/resend/errors.rb](), [lib/resend/request.rb:45-51]() ## Error Hierarchy and Classes The SDK defines a structured hierarchy of error classes inheriting from `StandardError`. This allows developers to rescue specific types of failures, such as rate limiting or internal server errors, or catch all SDK-related issues using the base `Resend::Error` class. ### Class Diagram The following diagram illustrates the inheritance structure of the Resend error classes: ```mermaid classDiagram class StandardError class Resend_Error["Resend::Error"] class ClientError["ClientError (4xx)"] class ServerError["ServerError (5xx)"] class InternalServerError["InternalServerError (500)"] class InvalidRequestError["InvalidRequestError (400, 401, 404, 422)"] class RateLimitExceededError["RateLimitExceededError (429)"] StandardError <|-- Resend_Error Resend_Error <|-- ClientError Resend_Error <|-- ServerError ServerError <|-- InternalServerError ServerError <|-- InvalidRequestError ServerError <|-- RateLimitExceededError ServerError <|-- NotFoundError ``` Sources: [lib/resend/errors.rb:6-40]() ### Summary of Error Classes | Class | HTTP Code(s) | Description | | :--- | :--- | :--- | | `Resend::Error` | N/A | Base class for all Resend-specific errors. | | `InvalidRequestError` | 400, 401, 404, 422 | Raised for malformed requests, authentication failures, or validation errors. | | `RateLimitExceededError` | 429 | Raised when the API rate limit is reached. Includes metadata for retries. | | `InternalServerError` | 500 | Raised when the Resend API encounters an unexpected server-side issue. | | `NotFoundError` | 404 | Specifically for resources that do not exist (often mapped to `InvalidRequestError`). | Sources: [lib/resend/errors.rb:33-40](), [lib/resend/request.rb:86-104]() ## API Error Processing The `Resend::Request` class is responsible for executing HTTP calls and inspecting the response. If the response status code indicates a failure (anything other than 200 or 201), the SDK extracts the error message and status code to raise the appropriate exception. ### Request Flow and Error Detection The following sequence diagram shows how the `perform` method handles errors during the API lifecycle: ```mermaid sequenceDiagram participant SDK as SDK Module participant Req as Resend::Request participant HTTP as HTTParty participant API as Resend API SDK->>Req: perform() Req->>HTTP: send(verb, url, options) HTTP->>API: HTTP Request API-->>HTTP: HTTP Response (e.g., 422) HTTP-->>Req: Response Object Req->>Req: check_json!(resp) Note right of Req: Raises InternalServerError if not JSON Req->>Req: process_response(resp) Req->>Req: handle_error!(data, resp) Req--xSDK: raise Resend::Error::InvalidRequestError ``` Sources: [lib/resend/request.rb:34-51](), [spec/request_spec.rb:14-26]() ### Rate Limit Metadata The `RateLimitExceededError` (status code 429) is unique as it captures specific headers from the Resend API to assist with request throttling and retry logic. * `rate_limit_limit`: The total limit allowed. * `rate_limit_remaining`: The number of requests remaining in the current window. * `rate_limit_reset`: The time when the limit resets. * `retry_after`: The number of seconds to wait before retrying. Sources: [lib/resend/errors.rb:20-31](), [spec/request_spec.rb:76-96]() ## Client-Side Validation In addition to API errors, the SDK performs client-side validation on method arguments. These typically raise standard Ruby `ArgumentError` exceptions before a network request is ever attempted. ### Common Validation Scenarios * **Missing Identifiers**: Methods in the Contacts API require either an `:id` or `:email`. If neither is provided, an `ArgumentError` is raised with the message `"Missing \`id\` or \`email\` field"` (matching Node.js SDK format). * **Missing Required Parameters**: For segment operations, if a `segment_id` is missing when adding or removing a contact, an `ArgumentError` is raised. * **Webhook Verification**: The `Resend::Webhooks.verify` method raises specific errors if required headers (`svix-id`, `svix-timestamp`, `svix-signature`) are missing or if the signature is invalid. Sources: [CHANGELOG.md:16-20](), [spec/contacts/topics_spec.rb:112-124](), [spec/contacts_segments_spec.rb:87-91](), [spec/webhooks_spec.rb:264-325]() ## Webhook Signature Verification Errors When using `Resend::Webhooks.verify`, the SDK performs security checks on incoming payloads. Failures in this process raise standard errors with descriptive messages: | Error Message | Cause | | :--- | :--- | | `"payload cannot be empty"` | The raw request body was not provided. | | `"webhook_secret cannot be empty"` | The signing secret from the Resend dashboard was missing. | | `"svix-id header is required"` | The unique message ID header was missing. | | `"Timestamp outside tolerance window"` | The webhook is older than 5 minutes or too far in the future. | | `"No matching signature found"` | The calculated HMAC does not match the provided signature. | Sources: [spec/webhooks_spec.rb:211-335]() ## Conclusion Error handling in the Resend Ruby SDK provides a robust mechanism for managing both expected API constraints and unexpected server failures. By leveraging a structured hierarchy of error classes and providing detailed metadata for rate limits, the SDK enables developers to build resilient applications that can gracefully handle delivery interruptions and validation issues. Sources: [lib/resend/errors.rb](), [lib/resend/request.rb]()