429 Too Many Requests

This is an educational reference page about HTTP 429 Too Many Requests. The page itself is served as 200 OK so it can be indexed as HTTP documentation.

The user has sent too many requests in a given amount of time (rate limiting).

Specification

Registered in the IANA HTTP Status Code Registry as Too Many Requests. Defined in RFC 6585, Section 4.

What it means

HTTP 429 Too Many Requests means the client hit a rate limit. RFC 6585 defines it, not RFC 9110. The response SHOULD explain the limit and MAY include Retry-After. RFC 6585 does not say how the server identifies the client or counts requests, so the limit can be per user, API key, IP address, endpoint, or the whole service.

When to use it

Return 429 when a client exceeds a documented request quota.
Return 429 to slow down login, password reset, and signup attempts.
Use 503 Service Unavailable instead when the whole service is overloaded regardless of who is calling.

Common causes

A loop or retry bug that sends requests as fast as it can.
Many workers sharing one API key and one quota.
Several users behind one NAT or proxy IP, when the limit is per IP address.
Bursty traffic that exceeds a per-second limit even when the per-hour total is fine.

Headers involved

Retry-After gives the wait as seconds, such as Retry-After: 30, or as an HTTP date.
Many APIs add their own quota headers, such as X-RateLimit-Remaining. RFC 6585 does not define them, so read the provider's docs.

Client fixes

Wait for the Retry-After time before retrying. Without it, retry with exponential backoff and jitter.
Reduce request volume with caching, batching, or webhooks instead of polling.
Give each worker its own budget, or put a shared rate limiter in front of the API calls.

Server fixes

Send Retry-After so well-behaved clients know when to come back.
Explain which limit was hit and its window in the response body.
Send Cache-Control: no-store or make sure 429 is never stored. RFC 6585 says responses with 429 MUST NOT be stored by a cache.

Examples

API quota exceeded

GET /api/search?q=status HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOi...

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

{
  "type": "https://api.example.com/problems/rate-limit",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key allows 60 search requests per minute."
}

Common mistakes

Retrying 429 immediately in a tight loop. It extends the block and can get the key suspended.
Returning 429 without Retry-After or any detail. Clients guess, and most guess too short.
Returning 503 for per-client limits. 503 tells clients the whole service is down.

Developer notes

Treat Retry-After as the minimum wait. When several workers hit 429 at the same moment, add random jitter to each wait so they do not all retry at once and trip the limit again.

Questions

What does HTTP 429 Too Many Requests mean?

HTTP 429 means the client sent too many requests in a given amount of time and hit a rate limit.

How long should I wait after a 429?

Wait for the time in Retry-After if the response has one. Otherwise use exponential backoff with jitter.

Is 429 in RFC 9110?

No. 429 is defined in RFC 6585, Section 4, and registered in the IANA HTTP Status Code Registry.

Header and content rules

What RFC 6585 says about a 429 response, quoted from the RFC. The 4xx class rules also apply.

SHOULD (server; content): Explain the rate limit in the response content. Table row
The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. RFC 6585 §4
MAY (server; Retry-After): Send Retry-After with how long to wait. Optional. Table row
The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request. RFC 6585 §4
MUST NOT (cache; storage): Do not store the response. Table row
Responses with the 429 status code MUST NOT be stored by a cache. RFC 6585 §4

The same rules are in the response obligations table and its JSON.