Error Handling & Rate Limiting
Relevant source files
The following files were used as context for generating this wiki page:
The Resend .NET SDK provides a structured approach to managing API errors and usage constraints. It encapsulates service-level failures into specific exception types and tracks rate limit headers provided by the Resend API to ensure reliable email delivery and system stability.
This system distinguishes between transient network issues, client-side validation errors, and server-side quota enforcement. Developers can use the provided metadata to implement custom retry logic or integrate with durable workflow engines.
Exception Architecture
The SDK handles errors by throwing a ResendException when the API returns a non-success HTTP status code. This exception contains a StatusCode property for the HTTP response and an ErrorType enum that maps to specific Resend API error codes.
Sources: src/Resend/ResendException.cs, src/Resend/ErrorType.cs, tests/Resend.Tests/ResendClientTests.Inboxes.cs:115-121
Resend Error Types
The ErrorType enumeration categorizes failures ranging from authentication issues to schema validation errors.
| Error Type | Description |
|---|---|
ValidationError | Occurs when request fields fail server-side validation. |
RateLimitExceeded | Triggered when the client exceeds the allowed request frequency. |
DailyQuotaExceeded | Occurs when the account reaches its daily email limit. |
InvalidApiKey | Indicates the provided API key is incorrect or revoked. |
HttpSendFailed | A client-side error indicating the HTTP request could not be transmitted. |
Sources: src/Resend/ErrorType.cs:7-150
Client Exception Flow
The following diagram illustrates how the ResendClient processes a request and generates exceptions based on the API response.
The SDK translates HTTP status codes into specific functional errors to simplify application-level handling.
Sources: src/Resend/ResendException.cs, src/Resend/ErrorType.cs
Response Metadata and Rate Limiting
Successful requests return a ResendResponse<T>, which contains the actual data in the Content property. It also includes metadata regarding the current state of API quotas via the ResendRateLimit class.
Rate Limit Tracking
The ResendRateLimit object exposes headers sent by the Resend API. This allows applications to monitor remaining capacity before encountering a RateLimitExceeded error.
- Limit: The total number of requests allowed in a window.
- Remaining: The number of requests left in the current window.
- Reset: The timestamp when the current rate limit window resets.
Sources: src/Resend/ResendResponse.cs, src/Resend/ResendRateLimit.cs
This relationship allows developers to inspect usage limits on every successful call.
Sources: src/Resend/ResendResponse.cs, src/Resend/ResendRateLimit.cs, src/Resend/ResendException.cs
Idempotency and Retries
To prevent duplicate submissions during transient failures, the SDK supports idempotency keys for critical operations like sending emails and managing drafts.
Idempotency Logic
If a request fails due to a network interruption, you can retry using the same idempotencyKey. The API returns the original successful response if the key matches a previous request within a 24-hour window. Reusing a key with a different request body or while a request is active results in a 409 Conflict or ConcurrentIdempotentRequests error.
Sources: src/Resend/IResend.cs:46-59, src/Resend/ErrorType.cs:105-115
Durable Retries
For high-reliability environments, the SDK documentation recommends using durable execution libraries. These libraries manage retries and backoff strategies to handle transient network issues or temporary rate limit constraints.
- Hangfire: Processes background jobs with built-in retry logic.
- Temporal: Manages durable workflows and stateful execution.
Sources: examples/README.md:17-42
Validation and Conflict Handling
Specific API endpoints define unique error scenarios. For example, InboxCreateAsync may return a validation_error (422) if the domain is unverified or a conflict error (409) if the address is already in use.
| Status Code | Error Mapping | Scenario |
|---|---|---|
| 403 | validation_error | Team reached inbox limit for the current plan. |
| 404 | not_found | Requested resource (e.g., Email ID) does not exist. |
| 422 | validation_error | Domain lacks DKIM/SPF verification or input schema is invalid. |
| 451 | security_error | Request blocked due to account-level security issues. |
Sources: src/Resend/IResend.cs:1092-1102, tests/Resend.Tests/ResendClientTests.cs:150-160
Summary
Error handling in the Resend .NET SDK is centralized through ResendException and the ErrorType enum, providing developers with clear reasons for API failures. By monitoring the ResendRateLimit provided in every response and utilizing idempotency keys, applications can maintain high reliability even during periods of heavy usage or transient network instability.
Sources: src/Resend/ResendException.cs, src/Resend/ResendResponse.cs, src/Resend/ErrorType.cs