HTTP 429 Too Many Requests – Free, Online, Private

What HTTP 429 means

429 is the rate-limit status from RFC 6585. The client should slow down. Retry-After may say how long to wait, as a date or as a number of seconds. The body can name the limit. A 429 is not a permanent ban unless you say so. It is also not a 503, which means the server is unhappy for everyone rather than this client going too fast.

429 Too Many Requests belongs to the 4xx client error class. Clients that only look at the class will group it with its neighbors. Clients that care about the exact code should use the narrower rule on this page, because the class is only the first digit.

When you see HTTP 429

When you see HTTP 429 Too Many Requests, stop on that exact status line. 429 Too Many Requests means the client has sent too much traffic in a given time. The trace that usually produces it: A tight retry loop crossed the limit. The 4xx client error class only tells you the first digit. A neighbor in that class is a different fault, and the fix on this page does not transfer to it.

Return 429 when this client has crossed a quota you enforce. Send Retry-After if you know when a retry is welcome. Use 503 if the whole service is shedding load regardless of who calls. Do not return 200 with an error field for a limit. Clients will not slow down.

How to fix HTTP 429

To fix HTTP 429, change the condition that made the server choose Too Many Requests. Wait. Honor Retry-After if it is present. Back off if it is not. Do not fan out more workers. A retry storm is how a small limit becomes an outage. After the indicated delay, once, with backoff if you are still limited. Not in a tight loop. If the log line is a different code, leave this page. The mix-up people make with 429 is this one: 503 is service-wide unavailability. 402 is a billing refusal. 425 is early data. 429 is this client's rate.

• Several workers shared one API key and the budget was counted per key.
• Retry-After was missing, so the client retried immediately and extended the lockout.
• A proxy and the origin both counted the same request and the tighter limit won.

An access log that only stores 429 is not enough to tell these apart. Keep the method, the path, and a request id. Do not keep the Authorization header or a request body that might be a token. The status explains the outcome. It is not a place to echo secrets back to the client either.

Example response

HTTP 429 Too Many RequestsHTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"error":"rate limit"}

Retry-After: 30 means wait 30 seconds. The client should not send another request on that key before then. If you omit the header, well-behaved clients back off exponentially anyway. A 429 page for a browser should be honest that the person clicked too fast or a script looped.

What the client should do

Wait. Honor Retry-After if it is present. Back off if it is not. Do not fan out more workers. A retry storm is how a small limit becomes an outage.

Do not cache 429 as the resource. A shared cache that stored it would rate-limit people who never called you.

After the indicated delay, once, with backoff if you are still limited. Not in a tight loop.

Codes people confuse with HTTP 429

503 is service-wide unavailability. 402 is a billing refusal. 425 is early data. 429 is this client's rate.