Why you're getting a 429 Too Many Requests error

A 429 is defined in RFC 6585 §4, and the definition is deliberately thin: it says the status code "indicates that the user has sent too many requests in a given amount of time", and then explicitly declines to say more. In its own words, the specification "does not define how the origin server identifies the user, nor how it counts requests." That single sentence is the reason 429s are confusing in practice. Every part of the accounting is left to the server: — Who you are. The counter may be keyed on your API key, your account, your OAuth client, your session cookie, or just your source IP. Two of your services sharing one key share one budget. Two of your users behind one corporate NAT may share one budget too. — What counts as a request. The limit may be applied per endpoint, across the whole API, or shared among several servers. A read and a write may cost different amounts against the same budget. — What "a given amount of time" means. Fixed windows, sliding windows, and token buckets all produce different refusals from the same nominal "100 per minute", and the server does not have to tell you which it uses. One thing the specification is firm about: responses with a 429 must not be stored by a cache. If you are seeing a 429 served repeatedly and instantly, with no variation, suspect an intermediary that is misbehaving rather than the origin.

Most client code that handles Retry-After handles half of it. The field is defined in RFC 9110 §10.2.3 with this grammar: Retry-After = delay-seconds / HTTP-date Both forms are legal and you will meet both in the wild. Delay-seconds is a non-negative integer count of seconds to wait: Retry-After: 120 HTTP-date is an absolute timestamp. The format required for generating it is IMF-fixdate (RFC 9110 §5.6.7), which always ends in GMT: Retry-After: Sun, 06 Nov 1994 08:49:37 GMT Two things routinely go wrong here. The first is parsing: code that does parseInt(retryAfter) on a date string gets NaN, and code that treats NaN as zero retries immediately — which on most APIs extends the penalty rather than ending it. Branch on whether the value is all digits before deciding which parser to use. The second is clock skew. An absolute date is only as good as your machine's clock, and a client running a few minutes fast will retry early every time. The 429 response also carries a Date header holding the server's own view of now; compute the wait as the difference between the Retry-After date and that Date header, not against your local clock. Note also that recipients are expected to accept two obsolete date formats (rfc850-date and asctime-date) even though senders should no longer produce them, so a strict parser can still fail on a compliant-enough server.

Alongside Retry-After you will often see a family of headers describing the budget itself — typically X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. These are conventions, not a standard. Nothing defines their units, so they differ between providers, and this is where integrations quietly break. X-RateLimit-Reset is the worst offender because it has at least three readings in common use: — a Unix timestamp in seconds, meaning "the window resets at this absolute moment" — a number of seconds remaining until the window resets — a Unix timestamp in milliseconds The values look similar enough that the wrong reading survives testing. A ten-digit number is almost certainly a Unix timestamp in seconds; a small number like 59 is almost certainly a duration. Rather than infer, check the provider's documentation once and pin the interpretation in your client — and prefer Retry-After when the response gives you both, since its units are actually specified. There is an IETF effort to standardise this area, draft-ietf-httpapi-ratelimit-headers, which defines RateLimit and RateLimit-Policy fields to replace the ad-hoc X-RateLimit-* set. It is an active Internet-Draft and has not been published as an RFC, so treat any RateLimit-* headers you receive today as provider-specific until that changes.

This is the case that sends people to search engines, and it is almost never a bug in the server. Common causes, roughly in order of how often they turn out to be the answer: — The counter is not yours alone. If the limit is keyed on IP, everything sharing your egress address shares your budget: other pods on the node, a NAT gateway, a CI runner pool, colleagues in the same office. Your service's own request rate can be well under the limit while the address's rate is not. — Burst versus sustained. A token bucket that permits 100 requests per second will still refuse 100 requests fired in the same 10 milliseconds if its burst capacity is smaller. Your average is fine; your instantaneous rate is not. — Fixed-window edges. With a fixed window, a burst at the end of one window and another at the start of the next are both legal individually, but they land within a few seconds of each other. Any sliding-window or per-second limit layered on top will reject the second burst. — More than one limit applies. Providers commonly enforce several simultaneously — per second, per minute, per day, plus a concurrency cap on in-flight requests. Staying under the per-second rate says nothing about the daily quota, and a concurrency cap can refuse you at a very low request rate if your requests are slow and overlapping. — Your retries are counted too. Requests that fail and are retried usually count against the budget. A retry storm after a blip can exhaust a limit that your steady-state traffic never approaches — which is why retries need backoff and jitter rather than a fixed delay. — The refusal came from somewhere else. A CDN, WAF, API gateway, or load balancer in front of the origin can issue its own 429 under its own policy, and its limits are usually neither documented alongside the API's nor reported in the API's own headers. — Distributed counters settle late. When a limit is enforced across several nodes sharing state, the count each node sees can briefly lag reality, so the effective limit near a boundary is fuzzier than the published number. The practical diagnostic: log the full response headers of the 429 itself, not just the status. The combination of which rate-limit headers are present, what Retry-After says, and whether a Via, Server, or CDN header names an intermediary will usually identify which of the above you are looking at within one incident.