429 Too Many Requests

429 means the client has sent too many requests in a given time window. Pair with `Retry-After` header (seconds or HTTP-date) to tell clients when to retry.

intermediate RFC 6585 §4 (429), RFC 7231 §7.1.3 (Retry-After)

What the RFC says

The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting"). The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait. (RFC 6585 §4) — RFC 6585 §4 (429), RFC 7231 §7.1.3 (Retry-After)

Example

GET /api/items HTTP/1.1

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1730000000

{
  "error": "rate_limited",
  "detail": "Quota: 100 requests/minute. Retry in 60s."
}

Real-world implementations

GitHub API: 5,000 reqs/hour (authenticated), exposed via `X-RateLimit-*` headers.
Twitter/X: 429 with `x-rate-limit-reset` (Unix epoch).
Cloudflare: 429 + `Retry-After` for triggered firewall rules.

Common misuses (don't do this)

Returning 429 without `Retry-After` — clients have no signal when to retry, often retry immediately and trigger more 429s.
Using 503 for rate limiting — 503 means 'server overloaded', 429 means 'you specifically'. Use the right one.
Setting `Retry-After: 0` — meaningless. Use 1 or fully specify the wait.

Use cases

API rate limit implementation
DDoS / abuse mitigation
Quota enforcement
Bot management

Get the RFC reference for any HTTP response

httpwut takes a curl response and explains the status code + headers + the RFC sections you should actually read. Built for HTTP debugging that goes deeper than 'lol 500'.

Open httpwut