429 Too Many Requests

What 429 means

429 means you have hit a rate limit. The request was not processed, and the correct response is to wait and try again rather than to retry immediately - which is precisely what a naive retry loop does, turning a rate limit into a sustained hammering.

The single most important header here is Retry-After, which tells the client how long to wait. It may be a number of seconds or an HTTP date. Without it, clients guess, and they generally guess too aggressively. Sending it is the difference between a client that backs off correctly and one that makes your problem worse.

Many APIs also send X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (or the standardised RateLimit-* equivalents), which let a well-behaved client slow down before hitting the limit at all. That is far better than reacting after the fact.

On the client side, the right pattern is exponential backoff with jitter, honouring Retry-After when present. Jitter matters more than it seems: without it, many clients rate-limited at the same moment all retry at the same moment, producing a thundering herd that trips the limit again.

Common causes of a 429

• Genuinely exceeding a documented request quota.
• A retry loop with no backoff, so a transient failure becomes a sustained burst.
• Missing or ineffective client-side caching, causing repeated identical requests.
• Concurrency higher than intended - a parallel map over a large array with no limit.
• A shared API key across several services, so one consumer's traffic exhausts everyone's quota.
• A limit applied per IP where many users sit behind one NAT or proxy.

How to fix a 429

• Honour Retry-After. If it is absent, use exponential backoff with jitter.
• Read the RateLimit-* headers and throttle before hitting the limit.
• Cache responses and deduplicate identical in-flight requests.
• Bound concurrency explicitly rather than firing off unbounded parallel requests.
• Use separate API keys per service so quotas are attributable and isolated.
• Batch requests where the API supports it.

Headers this status expects

• Retry-After - seconds or an HTTP date. Send this; without it clients guess badly.
• RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset - let clients throttle proactively.

Should a client retry?

Retry after waiting - Retry-After if present, otherwise exponential backoff with jitter. Never retry immediately.

FAQ

How long should I wait after a 429?

Exactly as long as Retry-After says, if it is present. If not, back off exponentially with jitter - for example 1s, 2s, 4s, 8s each plus a random fraction - and cap the total. Retrying immediately makes the situation worse.

Why is jitter important in backoff?

Because clients rate-limited at the same instant will otherwise all retry at the same instant, producing a synchronised burst that trips the limit again. A random offset spreads them out.

429 or 503 for an overloaded server?

429 when this specific client has exceeded its quota - the problem is attributable to them. 503 when the server as a whole cannot cope. Both should carry Retry-After.

Should a 429 count against the rate limit?

Generally not, and it is worth checking - if rejected requests consume quota, a misbehaving client can lock itself out indefinitely and never recover.

Often confused with

• 503 Service Unavailable The server is temporarily unable to handle the request - overloaded or down for maintenance.
• 403 Forbidden The server understood the request and is refusing it - authentication will not help.