Rate-limit headers and 429
The RateLimit and X-Quota headers on every answer, handling 429 with Retry-After, and the 503 overloaded rule.
Every answer to an authenticated call carries:
| Header | Meaning |
|---|---|
RateLimit-Limit | units allowed per minute |
RateLimit-Remaining | units left in this minute |
RateLimit-Reset | seconds until the minute window resets |
X-Quota-Limit | units allowed this month (UTC) |
X-Quota-Remaining | units left this month |
X-Request-Weight | units this call cost |
#429
429 rate_limited: this minute's units are spent (or too many wrong keys came from your address). WaitRetry-Afterseconds and retry.429with a monthly quota code: this month's units are spent. Retrying will not help before the next month (or an upgrade). The SDKs do not retry it.
#503
503 overloaded means the API is shedding heavy requests under load (lower tiers first, Business last). Retry after Retry-After. 503 api_disabled means maintenance.
#Retrying well
Retry 429 rate_limited, 502, 503 and 504 with exponential backoff and jitter, honouring Retry-After; never retry other 4xx. Retry a write only with the same Idempotency-Key. The SDKs do all of this for you.