API Rate Limit and 429 Debugging

Retry-After, RateLimit headers, quotas, client backoff and production incident evidence. Last updated August 31, 2026.

HTTP 429 means the client sent too many requests in a period of time, and MDN notes that a Retry-After header may tell the client how long to wait before retrying. See MDN 429 Too Many Requests and MDN Retry-After. IETF rate limit header drafts also describe quota signals such as remaining quota and reset timing; production APIs may use standard, draft or vendor-specific names.

Capture the response

curl -i https://api.example.com/search?q=test
curl -sS -D rate-limit-headers.txt -o response.json https://api.example.com/search?q=test
curl -sS -w "\nstatus=%{http_code} total=%{time_total}s\n" https://api.example.com/search?q=test

Headers to inspect

Header	Meaning to check	Debugging note
`Retry-After`	How long the client should wait before another request.	May be seconds or an HTTP date.
`RateLimit-Limit`	Quota limit in the active window.	Some APIs expose this name, others use vendor prefixes.
`RateLimit-Remaining`	Remaining quota near the response time.	Do not treat a positive value as a guarantee under concurrency.
`RateLimit-Reset`	When quota may reset.	Interpret carefully because deployments vary between seconds and timestamps.
`X-RateLimit-*`	Legacy or vendor-specific quota headers.	Document the API provider behavior before coding a client.

Client backoff pattern

1. Stop immediate retry loops.
2. Respect Retry-After when it is present.
3. Add exponential backoff with jitter.
4. Queue or batch low-priority requests.
5. Separate per-user, per-token and per-IP quota evidence.
6. Log request id, status, quota headers and retry delay.

Server-side questions

Is the limit keyed by IP, user, API token, tenant, route or organization?
Are browser preflight requests counted against the same quota as real API calls?
Does the gateway, CDN, reverse proxy or application own the 429 response?
Do error responses include enough headers for clients to slow down correctly?
Can internal jobs bypass public limits safely without hiding abusive loops?

Incident note template

endpoint:
client identity:
status:
retry-after:
ratelimit-limit:
ratelimit-remaining:
ratelimit-reset:
request volume:
window:
owner layer:
client fix:
server fix:

A healthy rate limit failure should tell a client how to slow down. A noisy 429 without retry or quota evidence turns protection into guesswork.