Relevant source files

The following files were used as context for generating this wiki page: - [resend/exceptions.py](https://github.com/resend/resend-python/blob/main/resend/exceptions.py) - [tests/exceptions_test.py](https://github.com/resend/resend-python/blob/main/tests/exceptions_test.py) - [tests/emails_test.py](https://github.com/resend/resend-python/blob/main/tests/emails_test.py) - [tests/topics_test.py](https://github.com/resend/resend-python/blob/main/tests/topics_test.py) - [tests/contact_topics_test.py](https://github.com/resend/resend-python/blob/main/tests/contact_topics_test.py) - [tests/contacts_test.py](https://github.com/resend/resend-python/blob/main/tests/contacts_test.py) - [tests/webhooks_test.py](https://github.com/resend/resend-python/blob/main/tests/webhooks_test.py)

# Error Handling & Exceptions The Resend Python SDK implements a robust error handling system designed to map API response codes and error types to specific Python exceptions. This system allows developers to catch specific error conditions—such as rate limits, validation errors, or authentication issues—and respond programmatically with suggested actions provided by the SDK. The core of the system is the `ResendError` base class, which captures essential metadata from the API, including HTTP status codes, error types, and human-readable messages. In addition to server-side errors, the SDK also raises standard Python exceptions like `ValueError` for client-side input validation failures. Sources: [resend/exceptions.py:1-24](), [tests/exceptions_test.py:11-14]() ## Exception Hierarchy The SDK utilizes a class-based hierarchy for exceptions. Every server-side error inherits from `ResendError`, providing a consistent interface for accessing error metadata such as `code`, `error_type`, and `suggested_action`. ```mermaid classDiagram class Exception class ResendError { +code: Union[str, int] +error_type: str +message: str +suggested_action: str +headers: Dict } class MissingApiKeyError class InvalidApiKeyError class ValidationError class MissingRequiredFieldsError class RateLimitError class ApplicationError class NoContentError Exception <|-- ResendError Exception <|-- NoContentError ResendError <|-- MissingApiKeyError ResendError <|-- InvalidApiKeyError ResendError <|-- ValidationError ResendError <|-- MissingRequiredFieldsError ResendError <|-- RateLimitError ResendError <|-- ApplicationError ``` The diagram shows the inheritance structure of the SDK's exception classes. Sources: [resend/exceptions.py:17-171](), [tests/exceptions_test.py:7-10]() ### Key Exception Classes | Exception Class | HTTP Code | Description | Suggested Action | | :--- | :--- | :--- | :--- | | `ResendError` | N/A | Base class for all server-side SDK errors. | Inspect `code` for details. | | `MissingApiKeyError` | 401 | Raised when the API key is missing from headers. | Include the Authorization header. | | `InvalidApiKeyError` | 403 | Raised when the provided API key is invalid. | Generate a new key in the dashboard. | | `ValidationError` | 400/422 | Raised when the request body has invalid fields. | Check error message for field list. | | `MissingRequiredFieldsError` | 422 | Raised when mandatory fields are omitted. | Check for missing required fields. | | `RateLimitError` | 429 | Raised when quotas or rate limits are exceeded. | Reduce request rate or wait. | | `ApplicationError` | 500 | Raised when a server-side error occurs at Resend. | Contact Resend support. | | `NoContentError` | N/A | Raised when an expected response body is empty. | Contact Resend support. | Sources: [resend/exceptions.py:44-171](), [tests/exceptions_test.py:21-60]() ## Error Dispatching Logic The SDK provides a centralized function, `raise_for_code_and_type`, to map API responses to the correct exception class. This function evaluates both the HTTP status code and the specific `type` string returned in the API JSON payload. ```mermaid flowchart TD Start[API Response Received] --> CodeCheck{Code in ERRORS?} CodeCheck -- No --> RaiseBase[Raise ResendError] CodeCheck -- Yes --> TypeCheck{Type in Sub-Dict?} TypeCheck -- No --> RaiseBase TypeCheck -- Yes --> RaiseSpecific[Raise Specific Exception] RaiseBase --> End[Exception Handled by User] RaiseSpecific --> End ``` This flowchart illustrates how the SDK determines which exception to raise based on the API response. Sources: [resend/exceptions.py:184-245](), [tests/exceptions_test.py:11-20]() ### Error Mapping Table The `ERRORS` dictionary maps status codes to a sub-dictionary of error types and their corresponding classes. | Status Code | Error Type | Resulting Class | | :--- | :--- | :--- | | 400 | `validation_error` | `ValidationError` | | 401 | `missing_api_key` | `MissingApiKeyError` | | 403 | `invalid_api_key` | `InvalidApiKeyError` | | 422 | `missing_required_fields` | `MissingRequiredFieldsError` | | 429 | `rate_limit_exceeded` | `RateLimitError` | | 429 | `daily_quota_exceeded` | `RateLimitError` | | 500 | `application_error` | `ApplicationError` | Sources: [resend/exceptions.py:174-182]() ## Client-Side Validation The SDK also performs client-side validation before making network requests. If required parameters are missing from method calls (e.g., missing `contact_id` or `email` in a contact lookup), the SDK raises a standard Python `ValueError`. ### Common Client-Side Errors * **Contact Management**: `resend.Contacts.get()` and `resend.Contacts.remove()` raise `ValueError` if neither `id` nor `email` is provided. * **Topics**: `resend.Contacts.Topics.list()` raises `ValueError` if both `contact_id` and `email` are absent. * **Segments**: `resend.Contacts.Segments.add()` raises `ValueError` if the contact identifier is missing. Sources: [tests/contacts_test.py:101-107](), [tests/contact_topics_test.py:73-80](), [tests/contacts_segments_test.py:29-34]() ## Webhook Verification Errors The `Webhooks.verify()` method performs security checks on incoming webhook payloads. Unlike standard API errors, these are triggered by signature or timestamp mismatches. | Error Condition | Exception Raised | Message | | :--- | :--- | :--- | | Empty Payload | `ValueError` | "payload cannot be empty" | | Missing Secret | `ValueError` | "webhook_secret cannot be empty" | | Missing Header | `ValueError` | "svix-id header is required" | | Invalid Timestamp | `ValueError` | "invalid timestamp format" | | Expired Signature | `ValueError` | "timestamp outside tolerance window" | | Mismatched Signatures | `ValueError` | "no matching signature found" | Sources: [tests/webhooks_test.py:165-225]() ## Metadata and Headers The `ResendError` class and its subclasses capture HTTP response headers. This is particularly useful for `RateLimitError`, where headers such as `retry-after`, `x-ratelimit-remaining`, and `x-ratelimit-reset` provide context on when to resume requests. ```python # Example of metadata captured in RateLimitError # Sources: tests/exceptions_test.py:77-90 headers = { "retry-after": "5", "x-ratelimit-limit": "100", "x-ratelimit-remaining": "0", } # Access via: exception.headers["retry-after"] ``` Sources: [resend/exceptions.py:38-41](), [tests/exceptions_test.py:77-106]() ## Summary The Resend SDK's error handling is designed to be highly specific. By mapping granular API error types to dedicated exception classes, it allows developers to implement precise recovery logic. Whether dealing with client-side `ValueError` for parameter validation or server-side `RateLimitError` for capacity management, the SDK provides the necessary metadata and suggested actions to resolve issues efficiently.