Rate Limiting System

Relevant source files

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

• src/lib.rs
• src/config.rs
• README.md
• src/usage.rs
• src/error.rs
• CONTRIBUTING.md

The Rate Limiting System protects the Resend API from excessive request volume and ensures the Resend client adheres to server-side constraints. It implements client-side throttling by default and provides structures to handle server-side rate limit enforcement.

This system operates primarily within the Config and Resend client implementation, utilizing a token bucket algorithm to manage request flow. It distinguishes between proactive throttling (client-side) and reactive error handling (server-side).

Sources: src/lib.rs:4-10, README.md:37-41

Client-Side Throttling

The SDK performs proactive rate limiting to avoid reaching the Resend API limit of 10 requests per second. By default, the client restricts outgoing requests to 9 requests every 1.1 seconds.

Implementation Details

The Config struct maintains an internal RateLimiter using the governor crate. This limiter is shared across all clones of a single Resend client. Rate limiting only applies to the asynchronous version of the crate.

• Jitter: The system adds a jitter between 10ms and 50ms to requests to prevent synchronized bursts.
• Concurrency: The limiter is wrapped in an Arc to allow safe usage across parallel contexts.

Sources: src/config.rs:104-115, src/config.rs:165-175, src/config.rs:190-192

Configuration

You control the rate limit via environment variables or the ConfigBuilder.

Variable	Description	Default Value
RESEND_RATE_LIMIT	Maximum requests permitted per window.	9
(Internal Window)	The time period for the quota.	1.1 seconds

Sources: src/config.rs:153-157, README.md:37-39

Request Flow Logic

The following diagram illustrates how a request passes through the rate limiter before execution:

The diagram shows the sequence from request initiation to execution, highlighting the mandatory jitter and limiter checks.

Sources: src/config.rs:188-195

Server-Side Rate Limit Handling

When the Resend API returns a 429 Too Many Requests status, the SDK transforms the response into a specific error variant. This occurs if client-side limits are bypassed or if multiple distributed clients exceed the account quota.

Rate Limit Error Data

If a 429 error occurs, the system parses specific headers from the response to inform the user of the current state.

Header	Struct Field	Description
ratelimit-limit	ratelimit_limit	The total request limit for the window.
ratelimit-remaining	ratelimit_remaining	The number of requests left in the current window.
ratelimit-reset	ratelimit_reset	Seconds until the current window resets.

Sources: src/lib.rs:205-210, src/config.rs:200-210

Error Transformation Sequence

The sequence diagram demonstrates the transformation of a standard HTTP 429 error into a detailed internal error type containing quota metadata.

Sources: src/config.rs:198-215, src/error.rs:177-185

Account Usage and Quotas

The system provides the UsageSvc to retrieve current account-level rate limits and quotas. This allows applications to monitor their consumption of AI credits, automation runs, and emails.

UsageRateLimit Data Model

The UsageRateLimit struct represents the server's reported limit for the authenticated account.

• limit: The maximum number of requests allowed.
• duration: The window duration (e.g., "1000ms").

Sources: src/usage.rs:135-139, src/usage.rs:24-35

Retries and Multi-Client Scenarios

The internal rate limiter operates within a single process. If you scale your application horizontally, internal limits alone cannot prevent 429 errors. The SDK provides helper methods in the rate_limit module to catch these errors and retry requests.

Key retry behaviors:

1. Distributed Environments: Use the rate_limit module helpers to manage retries across different machines.
2. Shared Client: Use .clone() on a Resend client to ensure all local threads share the same token bucket. Avoid creating multiple clients with Resend::new().

Sources: src/lib.rs:12-22, CONTRIBUTING.md:12-14

Summary

The Rate Limiting System combines a proactive governor-based limiter (defaulting to 9 req/1.1s) with reactive header parsing for 429 responses. This dual approach minimizes API collisions while providing detailed feedback when account quotas are reached. Users should utilize the async client for built-in protection and the UsageSvc for monitoring account limits.

Sources: src/lib.rs:4-22, src/config.rs:150-175