Error Handling

Relevant source files

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

• src/error.rs
• src/lib.rs
• src/batch.rs
• src/rate_limit.rs
• CHANGELOG.md

Error handling in the Resend Rust SDK provides a structured way to manage failures arising from HTTP communication, API-specific constraints, and data parsing. The system categorizes errors into high-level types such as transport errors, rate limits, and structured API responses to enable precise recovery logic.

The SDK uses the thiserror crate to define a comprehensive Error enum and provides a specialized Result<T> type for all service operations. This ensures that developers can handle predictable API errors, such as DailyQuotaExceeded or InvalidIdempotencyKey, differently from transient network issues.
Sources: src/lib.rs:125-144, src/error.rs:5-15

Error Hierarchy and Types

The SDK centralizes error definitions in src/lib.rs and src/error.rs. The primary Error enum captures the broad categories of failure that occur during the request-response lifecycle.

The Error Enum

The Error enum distinguishes between client-side issues and server-side responses.

Variant	Description	Source
Http	Wraps reqwest::Error for network and transport failures.	src/lib.rs:128-129
Resend	Contains an ErrorResponse returned by the Resend API.	src/lib.rs:132-133
Parse	Occurs when the API response cannot be deserialized into the expected type.	src/lib.rs:136-140
RateLimit	A specialized variant for 429 errors, providing limit and reset details.	src/lib.rs:147-152
Other	Catch-all for generic error strings.	src/lib.rs:143-144

Sources: src/lib.rs:125-153

API Error Responses

When the Resend API returns an error, the SDK deserializes it into an ErrorResponse struct. This struct includes a status_code, a descriptive message, and a machine-readable name.

pub struct ErrorResponse {
    pub status_code: u16,
    pub message: String,
    pub name: String,
}

Sources: src/error.rs:11-16

The following diagram illustrates the flow of a failed request being converted into a structured SDK error.

The diagram shows how the SDK differentiates between transport failures, rate limits, and structured API error responses.
Sources: src/lib.rs:125-153, src/error.rs:11-142

Error Categorization (ErrorKind)

The ErrorKind enum maps the name field of an ErrorResponse to specific, typed variants. This allows developers to match against specific error conditions without parsing strings.

Common Error Kinds

The SDK recognizes over 20 distinct error types from the Resend API specification.

ErrorKind Variant	HTTP Status	Description
InvalidIdempotencyKey	400	Key must be between 1-256 characters.
MissingApiKey	401	Missing or invalid Authorization header.
EmailAboveQuota	403	Email content too large for current plan.
NotFound	404	The requested endpoint or resource does not exist.
ResourceLocked	409	Conflict during concurrent resource updates.
DailyQuotaExceeded	429	Reached daily email sending limit.
ServiceUnavailable	503	API is temporarily offline.

Sources: src/error.rs:25-142

Rate Limiting and Retries

The SDK manages rate limits through both automated client-side throttling and explicit error types for server-side enforcement.

Client-Side Throttling

The Resend client is automatically rate-limited to 9 requests per 1.1 seconds by default. This limit is configurable via the RESEND_RATE_LIMIT environment variable. This mechanism prevents predictable "Too Many Requests" errors before they occur.
Sources: src/lib.rs:4-11, README.md:37-41

Server-Side Rate Limit Errors

If the server returns a 429 error, the SDK populates the Error::RateLimit variant with headers provided by Resend:

• ratelimit_limit: Total allowed requests.
• ratelimit_remaining: Requests remaining in the current window.
• ratelimit_reset: Seconds until the limit resets.

Sources: src/lib.rs:147-152, CHANGELOG.md:315-316

Batch Validation Modes

In BatchSvc, error handling depends on the BatchValidation mode selected.

• Strict Mode (Default): If any email in a batch fails validation, the entire request fails, and the SDK returns a global error.
• Permissive Mode: The request succeeds, but the SendEmailBatchPermissiveResponse contains an errors vector detailing which specific indices failed.

The flow shows that Strict mode treats validation as an atomic operation, whereas Permissive mode allows for partial success.
Sources: src/batch.rs:56-91, src/batch.rs:104-120

Internal Testing of Errors

The SDK includes internal tests to ensure the ErrorKind enum stays synchronized with the Resend API documentation. The errors_up_to_date test parses the live Resend error documentation and asserts that every listed error code has a corresponding variant in the ErrorKind enum.
Sources: src/error.rs:146-218