Rate limits

The limit

1,000 requests per minute, per API key. Each key has its own bucket, so a test key and a live key don't share a limit. A batch send counts as one request per email it meters (so a 100-email batch consumes ~100 tokens), which is why batching is far more efficient than looping over /send. OAuth-connected agents are rate-limited the same way, per client.

The deliverability check additionally has a dedicated, tighter limit of 20 requests per minute, per key — it runs an AI analysis on every call, so the dedicated cap keeps an automated loop from running up cost. Over it you get the same 429 rate_limited (with Retry-After); no analysis runs.

Headers

Every response carries your current budget:

RateLimit"color:#ff7b72">-Limit: 1000
RateLimit"color:#ff7b72">-Remaining: 994
RateLimit"color:#ff7b72">-Reset: 37          # seconds until the window resets
Retry"color:#ff7b72">-After: 12             # only on a 429

Handling 429

A 429 returns rate_limited and sets Retry-After (seconds). The SDK retries automatically with backoff; to handle it yourself, wait Retry-After and retry the idempotent request.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded — retry after the indicated delay.",
    "request_id": "req_8f3c9a1b2d4e5f6071829304"
  }
}

When the limiter is unavailable

If the rate-limit check itself can't be evaluated (a rare backend fault), most endpoints fail open — your request proceeds, so a transient blip never blocks a critical send like a password reset. But for cost-bearing or bulk operations we instead fail closed and return 503 rate_limit_unavailable (retryable): the paid deliverability check (no analysis is run) and batch send (nothing is sent). It's safe to retry after a short backoff — the SDK already retries 503 for you.