429 Too Many Requests
The client has sent too many requests in a given period. The Retry-After header says how long to wait before trying again.
At a glance
- Status code
- 429 Too Many Requests
- Class
- 4xx, client error, the request itself is the problem
- Defined in
- RFC 6585
- Cacheable by default
- by explicit headers only
- Response body
- Should say when to retry.
In detail
Rate limiting. The request was valid and was refused for volume, not for content, so waiting and retrying the identical request is the correct response.
Always send Retry-After. Without it, every client invents its own backoff and the well-behaved ones end up penalised alongside the aggressive ones.
Honour Retry-After exactly, then add jitter. Fixed backoff across many clients produces a synchronised retry spike that trips the limit again.
Examples
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{"error":"rate_limited"}Things that catch people out
- Retry-After accepts either seconds or an HTTP date. Parsers that assume seconds will misread the date form as a very long wait.
- 429 responses are cheap to generate but not free. A limiter that returns 429 while still doing the expensive work provides no protection.
- A shared cache can store a 429 and serve it to clients that were not rate limited. Send Cache-Control: no-store.
Try it: HTTP Request Builder
Build a request with any method, headers and body, send it, and read the status line the server returns.
HTTP Request Builder
LOCAL · Browser-OnlyBuild and test HTTP requests with custom headers and body
Authentication
Headers
Generate Code
curl -X GET 'https://api.example.com/endpoint' \
-H 'Content-Type: application/json'Showing a sample URL. Enter your endpoint above to update the snippet.
Related HTTP status codes
All http status codes →503 Service Unavailable
The server is temporarily unable to handle the request, because it is overloaded or deliberately down for maintenance. The condition is expected to clear.
403 Forbidden
The server understood the request and refuses to fulfil it. Unlike 401, sending different credentials will not help.
402 Payment Required
Reserved for future use in the original specification, and now used in practice by APIs to signal that a plan limit or unpaid invoice is blocking the request.
431 Request Header Fields Too Large
The request headers are collectively or individually too large. Oversized cookies are the usual cause.
451 Unavailable For Legal Reasons
Access is denied because of a legal demand, such as a court order or a government blocking request.
500 Internal Server Error
The server hit an unexpected condition and cannot say anything more specific. It is the catch-all for unhandled exceptions.
Tools for this
- HTTP Request Builder Free online HTTP request builder - build and test HTTP requests with custom headers and body
- HTTP Headers Checker Free online HTTP headers checker - view HTTP response headers for any URL