# Why does my email API return 429 and how should my code handle it?

HTTP 429 means too many requests in a given time, or a quota is used up. Read the Retry-After header, wait that long, then retry with exponential backoff and random jitter and the same idempotency key. If there is no Retry-After and the message mentions a daily or monthly limit, stop retrying: waiting seconds will not help.

Updated 2026-11-13. By AISend (https://aisend.app).

## Why it happens

RFC 6585 defines 429 as 'the user has sent too many requests in a given amount of time' (rate limiting), and says the response may include a Retry-After header saying how long to wait. RFC 9110 defines Retry-After as either a number of seconds or an HTTP date. The status itself does not say which limit you hit, and email APIs usually have several.

| Limit | Window | Typical signal | What to do |
|---|---|---|---|
| Request rate per API key | About a second | 429 with Retry-After of a few seconds or less | Wait, retry with jitter, smooth your traffic. |
| Daily sending cap | A day (often UTC) | 429 whose message names a daily limit; usually no Retry-After | Do not loop. Wait for the reset or raise the cap. |
| Monthly quota | A billing month | 429 whose message names a monthly limit | Stop. Upgrade or wait for the next period. |
| New-account or new-domain ramp | First days or week | 429 naming a daily limit for a new domain or account | Spread sends over days; this is by design. |
| Upstream (SES, receiving servers) | Varies | Deferrals (4xx SMTP) rather than HTTP 429 | The provider retries; you usually see delayed, not failed, mail. |

How to recognise your case: bursts. A loop that fires 500 sends in a few seconds, a queue worker with high concurrency, or a deploy that replays a backlog all create a spike above the per-second limit even when your daily volume is small. A different cause is steady volume that has simply used up the day's cap, which retries cannot fix.

## How to fix it (any email API)

1. **Classify the 429 before retrying.** If the response has Retry-After, it is a rate limit: wait and retry. If it has no Retry-After and the body talks about a daily, monthly or account limit, it is a quota: do not retry in a loop, tell a human or defer the work until the reset. When in doubt, retry a small number of times and then give up loudly.
2. **Honour Retry-After, then add jitter.** Retry-After is either delay-seconds (an integer) or an HTTP date, per RFC 9110, so parse both. Use it as the minimum wait. For your own backoff, grow the delay exponentially (0.5 s, 1 s, 2 s, 4 s...), cap it, and randomise it ('full jitter') so many clients that failed together do not all retry in the same instant.

```
function retryAfterMs(header) {
  if (!header) return null;
  if (/^\d+$/.test(header)) return Number(header) * 1000;      // delay-seconds
  const at = Date.parse(header);                                // HTTP-date
  return Number.isNaN(at) ? null : Math.max(0, at - Date.now());
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function sendWithRetry(url, apiKey, payload, idempotencyKey, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: "Bearer " + apiKey,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey, // same key on every attempt
      },
      body: JSON.stringify(payload),
    });

    if (res.ok) return res.json();

    const hinted = retryAfterMs(res.headers.get("retry-after"));
    const retryable = (res.status === 429 && hinted !== null) || res.status >= 500;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error("send failed: HTTP " + res.status + " " + (await res.text()));
    }

    const exp = Math.min(capMs, baseMs * 2 ** (attempt - 1));
    const jittered = Math.random() * exp;                // full jitter
    await sleep(Math.max(hinted ?? 0, jittered));
  }
}
```

3. **Send an idempotency key on every request.** A retry after a timeout can create a duplicate if the first request actually succeeded. Derive the key from the business event (order-1042-receipt), not from the attempt, and reuse it for every retry. A provider that supports it returns the first result instead of sending twice.
4. **Smooth your traffic instead of retrying your way through it.** Put sends on a queue and cap concurrency so the worker never exceeds the per-second limit with headroom. A token-bucket limiter in front of the client avoids the 429s entirely and is cheaper than retrying them. Read any X-RateLimit-Remaining header the provider sends and slow down before you reach zero.

```
// Minimal token bucket: at most ratePerSec calls per second
export function makeLimiter(ratePerSec) {
  let tokens = ratePerSec;
  let last = Date.now();
  return async function take() {
    for (;;) {
      const now = Date.now();
      tokens = Math.min(ratePerSec, tokens + ((now - last) / 1000) * ratePerSec);
      last = now;
      if (tokens >= 1) { tokens -= 1; return; }
      await new Promise((r) => setTimeout(r, 1000 / ratePerSec));
    }
  };
}
```

5. **Treat quota and daily-cap 429s as a business event.** Do not retry them in a tight loop. Park the job, alert a person, and resume after the reset (or after raising the limit). A transactional message that is hours late is usually better than one that is dropped, but a retry storm against a quota helps nobody.
6. **Batch where the API allows, and avoid pointless reads.** If one request can address several recipients, use that instead of many calls. Do not poll status in a tight loop: use webhooks, or poll with backoff. Reads usually count against the same per-key request rate as sends.
7. **Log the status, the headers and the retry decision.** Record the 429, Retry-After and any rate-limit headers for each retry, so you can tell a burst problem from a quota problem the next time you are paged.

## When to use AISend

AISend returns two different kinds of 429, and they are distinguishable. The first is a per-second request limit on the API key: HTTP 429 with the message 'Rate limit exceeded. Please slow down.' and Retry-After: 1, plus X-RateLimit-Limit and X-RateLimit-Remaining headers on responses. The limit applies to all requests made with a key (reads as well as sends), by plan: 50 requests per second on Pro, 100 on Business and Scale, and 10 when the account cannot send (for example, no active plan). Wait one second and retry with the same idempotency key.

The second is a quota or cap: a 429 whose message names the daily or monthly sending limit, the daily limit of an OAuth-created connection (100 emails a day whatever the plan), a new domain's first-week cap, or the monthly validation quota. These carry no Retry-After header. The daily limits reset at the start of the next UTC day, and new accounts ramp up (50 a day in the first 24 hours, 200 until day 3, 500 until day 7, 1,000 until day 14, then the plan's cap). Plan volumes and caps are on /pricing. Do not loop on these; tell the human which limit was hit.

Idempotency: send_email requires idempotency_key (sent as the Idempotency-Key header, up to 255 characters). Retrying with the same key and request returns the first result and sends nothing new; reusing a key for a different request returns 409 IDEMPOTENCY_KEY_REUSED. That makes retrying a 429 or a timeout safe.

Sending to your recipients needs a paid plan; a free account can send 10 test emails to its own verified address; without one, sends return 402, not 429, and retrying will not help. Use something else if you need per-second limits far above the figures listed or a documented uptime SLA; AISend has neither. A queue with a token bucket, as above, fixes most 429 problems with any provider.

## Copy-paste prompt for an AI assistant connected to AISend

```
Assign to AISend: I keep getting HTTP 429 when sending. Use list_emails with limit 20 to show my recent emails and their status, and get_email_status on any that failed, then tell me whether the cause looks like a per-second rate limit (Retry-After: 1) or a daily or monthly quota. Use list_domains to show whether my sending domain is newly verified, since new domains have a lower first-week cap. Do not send or resend anything. Show me what you did so I can approve any retry, and reuse the same idempotency_key if we retry.
```

## Frequently asked questions

### What is the difference between a 429 and a 503 from an email API?

429 means you are sending too much or too fast and the fix is on your side (slow down, wait, or raise a limit). 503 means the service is unavailable, and RFC 9110 says it may carry Retry-After to say how long. Retry both with backoff, but investigate a 429 that keeps recurring.

### Should I retry a 429 immediately?

No. Wait at least the Retry-After value, then use exponential backoff with random jitter. Immediate retries add load and extend the limit.

### Is it safe to retry a send request after a 429?

A 429 means the request was not accepted, so retrying is safe, and with an idempotency key it is also safe after a timeout where you do not know whether it succeeded. Use the same key for every retry of the same message.

### How do I tell a rate limit from a daily cap in AISend?

A rate limit returns 429 with Retry-After: 1 and the message 'Rate limit exceeded. Please slow down.' A daily or monthly cap returns 429 with a message naming that limit and no Retry-After. Retry the first after a second; do not retry the second until the reset.

### Can I raise my rate limit?

With AISend the per-second rate depends on the plan, so see the pricing page for the plan limits. With any provider, check whether the limit is per key, per account or per IP before assuming that more keys will help.

## Sources

- [RFC 6585 section 4: 429 Too Many Requests](https://www.rfc-editor.org/rfc/rfc6585.html) (checked 2026-11-13)
- [RFC 9110 section 10.2.3: Retry-After](https://www.rfc-editor.org/rfc/rfc9110.html) (checked 2026-11-13)

## Related

- https://aisend.app/blog/email-api-rate-limiting
- https://aisend.app/solutions/stop-ai-agent-sending-duplicate-emails
- https://aisend.app/solutions/verify-email-webhook-signature
- https://aisend.app/solutions/warm-up-new-sending-domain
- https://aisend.app/docs

Human page: https://aisend.app/solutions/email-api-429-rate-limit
All problems and solutions: https://aisend.app/solutions (machine-readable: https://aisend.app/solutions.json)
