429 Too Many Requests

Answer

429 Too Many Requests means the server is rate limiting you: you sent more requests than allowed in some time window. Wait, using Retry-After if it is present, and retry with exponential backoff.

429

Too Many Requests RFC 6585 §4

The client has sent too many requests in a given time and is being rate limited.

The server may say when to try again with Retry-After, in seconds or as a date. Clients should back off exponentially with jitter rather than retry immediately, which only extends the block. Many APIs also send non-standard X-RateLimit-* headers showing the limit and remaining budget.

Explained

429 was defined in RFC 6585, section 4. The server may include Retry-After, either as a number of seconds or as an HTTP date, telling you when to try again. Honor it; retrying sooner usually just resets or extends the window.

Limits can apply per API key, per user, per IP address or per endpoint, and many APIs have several at once (per second and per day, for example). Most APIs report the limit in headers such as X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; these names are common but not standardized, so check the API's docs.

When many clients back off by the same fixed delay, they retry in lockstep and trigger the limit again. Add random jitter to each delay so retries spread out.

Not every rate limiter uses 429. nginx's limit_req and limit_conn reply with 503 unless you set limit_req_status 429;, and some APIs use 403.

How to debug it

Read Retry-After and any X-RateLimit-* headers on the 429 response.
Count your real request rate: loops, retries inside retries, and parallel workers sharing one API key add up quickly.
Check whether the limit is per IP; serverless functions or CI runners behind a shared NAT can share one IP budget.
Implement exponential backoff with jitter, capped at a maximum delay, and stop after a few attempts.
Cache responses you request repeatedly and batch calls if the API supports it.

Gotchas

Retrying a 429 immediately in a tight loop can get the key or IP blocked outright.
Retry-After may be a date rather than seconds; parse both forms.
A 429 from a CDN or WAF in front of an API can have different limits than the API itself.

Related explainers

← All HTTP status codes