HTTP 429 Too Many Requests — What It Means & How to Debug

HTTP 429 Too Many Requests is an HTTP response status code that indicates the client has sent more requests in a given time window than the server allows. The response MUST include either a Retry-After header or a 429 response body indicating how long the client should wait before making another request.

What It Means

Defined in RFC 6585 Section 4, the 429 status code is the standard way for APIs to implement rate limiting. The server defines policies per client (identified by IP, API key, or user token) specifying a maximum number of requests per window — commonly per second, per minute, or per day.

The Retry-After header can be a date (Wed, 21 Oct 2025 07:28:00 GMT) or a number of seconds (120). Many APIs also include non-standard headers like X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset to help clients self-regulate.

When It’s Sent

• API key limits exceeded — A developer’s API key has exhausted its quota for the current window.
• Brute-force protection — Multiple failed login attempts from the same IP trigger rate limiting.
• Web scraping countermeasures — A bot sends requests faster than the server’s threshold.
• DDoS mitigation — A sudden traffic spike from a single source triggers automatic throttling.
• Tiered pricing enforcement — A free-tier user exceeds their 1,000 requests/hour limit while premium users have higher caps.

Real Example

The following curl command sends requests rapidly to trigger GitHub API rate limiting:

for i in {1..10}; do
  curl -v https://api.github.com/rate_limit 2>&1 | grep -E "< HTTP|Retry-After|X-RateLimit"
done

Expected response from a rate-limited endpoint:

< HTTP/1.1 200 OK
< X-RateLimit-Limit: 60
< X-RateLimit-Remaining: 58
...

< HTTP/1.1 403 Forbidden
< X-RateLimit-Remaining: 0
< Retry-After: 60
< X-RateLimit-Reset: 1718884800

Note: GitHub uses 403 rather than 429 for some rate limits. A real 429 response looks like:

< HTTP/1.1 429 Too Many Requests
< Retry-After: 120
< Content-Type: application/json
<
{
  "error": "rate_limit_exceeded",
  "message": "API rate limit exceeded. Retry in 120 seconds.",
  "retry_after_seconds": 120
}

How to Debug

Client-Side

1. Read the Retry-After header — Always check the response headers. The value tells you exactly how long to wait.
2. Track rate limits locally — Parse X-RateLimit-Remaining and X-RateLimit-Reset headers on every response and throttle accordingly.
3. Implement exponential backoff — Base delay on Retry-After multiplied by a factor that increases with consecutive 429s.
4. Add jitter — Randomize wait times slightly to prevent thundering herd when multiple clients retry simultaneously.
5. Request a higher quota — If you consistently hit limits, apply for a higher rate limit tier or use multiple API keys.

Server-Side

1. Choose a rate-limiting algorithm — Token bucket, sliding window, or fixed window each have trade-offs. Token bucket is smooth; fixed window is simple.
2. Identify clients correctly — Use API keys, OAuth tokens, or IP + User-Agent fingerprinting. Avoid relying on IP alone behind NAT or shared proxies.
3. Set appropriate limits — Base limits on your infrastructure capacity. Monitor 429 rates to find the sweet spot.
4. Return clear headers — Always include Retry-After and consider X-RateLimit-* headers so clients can self-throttle.
5. Handle distributed rate limiting — Use Redis or a similar fast store to track counters across multiple server instances.

Common Causes Table

FAQ

Related Codes

HTTP 503 Service Unavailable — The server is temporarily unable to handle the request.

HTTP 408 Request Timeout — The server timed out waiting for the request.

HTTP 403 Forbidden — The server understood the request but refuses to authorize it.