API Rate Limit Headers: What to Send With a 429, and How Clients Should Wait

What does a 429 status code mean?

429 Too Many Requests is the HTTP status for rate limiting. RFC 6585, published in April 2012, defines it in one sentence: "The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting")." The same section says the response "MAY include a Retry-After header indicating how long to wait before making a new request", and that "Responses with the 429 status code MUST NOT be stored by a cache" (RFC 6585, section 4).

The RFC leaves the rules to you: it "does not define how the origin server identifies the user, nor how it counts requests." Per API key, per IP, per token used: that is your call, and your documentation's job to explain.

HTTP/1.1 429 Too Many Requests 1
Content-Type: application/json
Retry-After: 30 2
RateLimit-Policy: "default";q=100;w=60 3
RateLimit: "default";r=0;t=30 4

{"error": "rate_limited", "message": "100 requests per minute per API key. Try again in 30 seconds."} 5

What do Retry-After, RateLimit and X-RateLimit headers mean?

Five ideas cover every rate limit header you will meet. The names change from API to API; the ideas do not.

Retry-After

How long to wait before the next request. RFC 9110: "The Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response." Its own examples are Retry-After: Fri, 31 Dec 1999 23:59:59 GMT and Retry-After: 120, "the delay is 2 minutes" (RFC 9110, 10.2.3). A 503 Service Unavailable may carry it too (RFC 9110, 15.6.4).

Limit

The quota for one window, such as 5,000 requests per hour. Usually x-ratelimit-limit or a variant of it.

Remaining

What is left of the quota in the current window. When it reaches 0, the next request is refused.

Reset

When the quota comes back. The one value with no common format: an epoch time, a duration or a timestamp, depending on the API (table below).

RateLimit-Policy and RateLimit

Two fields proposed by the IETF HTTPAPI working group to replace the many X- spellings. RateLimit-Policy states the quota (q), the window in seconds (w, optional), an optional unit (qu: requests, content-bytes or concurrent-requests) and an optional partition key (pk). RateLimit states the quota left (r) and the effective window in seconds within which no more than r may be used (t, optional). The latest version is draft -11 of 23 May 2026; it is still an Internet-Draft, not an RFC, and it expires on 24 November 2026 unless replaced (IETF datatracker).

How do GitHub, OpenAI, Anthropic and Discord write these headers?

Four popular APIs, four ways to say when the quota comes back. A client that talks to more than one of them needs a reset parser per API, or it can use Retry-After when it is sent. All four document it, but not every 429 carries it: GitHub sends it for secondary limits, and Anthropic's spend-cap 429 never has it.

All four docs read on 2026-10-21. GitHub adds that its rate limit values "can vary from one response to the next based on the location handling the request", so "avoid logic that depends on an exact remaining count." Anthropic notes it uses "the token bucket algorithm", so capacity "is continuously replenished up to your maximum limit, rather than being reset at fixed intervals."

Should my client retry this request?

Ask these four questions before every retry, in order. The first answer that says wait, retry or stop decides.

1. Is the status 429 or 503?

   No Do not retry on the rate limit path. One exception: GitHub can answer a rate limit with 403, so check its headers first.

   Yes Go on.

2. Have you hit your retry limit, or is this a limit that does not lift by itself?

   Stop Show the error. GitHub says to "throw an error after a specific number of retries"; Anthropic's spend-cap 429 has no retry-after and retrying "fails until access resumes".

   No Go on.

3. Is there a Retry-After header?

   Yes Wait at least that long. OpenAI also asks you to "add a small random delay so multiple clients don't retry at the same time" (OpenAI docs). Then retry.

   No Go on.

4. Is remaining 0, with a reset time you can read?

   Yes Wait until the reset, parsed in that API's own format. Then retry.

   No Back off with full jitter (next question). For a GitHub secondary limit, wait at least one minute first.

For requests that change data, such as a POST, retry only when the API says a 429 means the request was not processed, or when it supports idempotency keys. Otherwise a retry can run the same action twice.

How long should a client wait between retries?

When the server gives no wait time, use exponential backoff with full jitter: double the ceiling after every failed try, cap it, and wait a random time between zero and that ceiling. Marc Brooker's AWS Architecture Blog post (4 March 2015) writes it as sleep = random_between(0, min(cap, base * 2 ** attempt)). In his simulation "The no-jitter exponential backoff approach is the clear loser", and he concludes that jittered backoff "should be considered a standard approach for remote clients" (Exponential Backoff And Jitter).

// fetch with retries: Retry-After first, full jitter otherwise
// use it for reads, or for writes the API makes safe to repeat (idempotency keys)
async function fetchWithRetry(url: string, init: RequestInit = {}, maxRetries = 5) {
  const base = 1000
  const cap = 32_000
  const maxWait = 120_000 // never sleep longer than 2 minutes inside one call
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, init)
    if (res.status !== 429 && res.status !== 503) return res
    if (attempt === maxRetries) return res // give up, let the caller show the error

    let wait = Math.random() * Math.min(cap, base * 2 ** attempt) // full jitter
    const header = res.headers.get('retry-after')
    if (header) {
      const seconds = Number(header)
      const ms = Number.isNaN(seconds) ? Date.parse(header) - Date.now() : seconds * 1000
      if (ms > maxWait) return res // too long to wait here, let the caller decide
      if (ms >= 0) wait = ms + Math.random() * 1000 // at least Retry-After, plus a little jitter
    }
    await res.body?.cancel() // free the connection before sleeping
    await new Promise((resolve) => setTimeout(resolve, wait))
  }
}

A Retry-After that is not a number and not a valid date gives NaN, so the loop falls back to the jittered wait, as OpenAI recommends when the header is "missing or invalid". maxRetries caps the number of tries and maxWait caps a single wait; OpenAI's advice is to "Limit both the number of attempts and the total time spent retrying".

What should each side do?

Quick questions