Every API that enforces a rate limit has to tell clients three things: what the limit is, how much of it is left, and how long to wait once it is used up. HTTP has one standard answer for the last of these and, at the time of writing, only drafts and conventions for the first two.
This guide covers what is standardised today, what the IETF is still working on, how a client should react to a 429, and what a server should send. It includes retry helpers in JavaScript and Python that you can use as they are.
What is standard today
The status code is settled. RFC 6585 defines 429 Too Many Requests for a client that has sent too many requests in a given time, and says the response may include a Retry-After header.
Retry-After is defined in RFC 9110, section 10.2.3. Its value takes one of two forms: a number of seconds to wait, or an HTTP date after which to retry.
Retry-After: 30
Retry-After: Sun, 15 Nov 2026 10:31:00 GMTA client has to handle both. The seconds form is the more robust of the two because it does not depend on the client and server clocks agreeing. The same header is used with 503 Service Unavailable, so one piece of client code covers both throttling and temporary overload.
The legacy X-RateLimit headers
Most APIs also send some variant of X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. These were never standardised, and the names hide real differences. The reset value is the main one: GitHub documents x-ratelimit-reset as a time in UTC epoch seconds, while other APIs send the number of seconds remaining in the window.
A client written against one API therefore cannot be reused against another without reading the documentation. Treat these headers as provider-specific: useful for dashboards and for slowing down before you hit the limit, but not something generic client code can interpret. For the decision that matters, when to retry, rely on Retry-After.
The IETF RateLimit headers
The IETF's HTTPAPI working group has been standardising a replacement in RateLimit header fields for HTTP. At the time of writing (November 2026) it is still an Internet-Draft, not an RFC: the current revision is draft 11, dated 23 May 2026, and it is listed as a working group document on the standards track. Its details can still change before publication.
The design has changed a good deal from early drafts, which defined three headers named RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Implementations of those earlier revisions are still in use, so you will meet those names too. The current draft defines two fields, both using the Structured Fields syntax:
RateLimit-Policy: "burst";q=100;w=60, "daily";q=1000;w=86400
RateLimit: "burst";r=50;t=30RateLimit-Policy describes the server's quota policies and stays the same from one response to the next. Each policy has a name and a required q parameter, the quota. The optional w gives the window in seconds, qu names the unit when it is not requests, and pk carries a partition key that identifies which bucket the request was counted against.
RateLimit reports the current state for a named policy. The required r is the quota remaining and the optional t is the number of seconds until that quota is restored. In the example above the client has 50 of 100 requests left and the window resets in 30 seconds.
Three points in the draft are worth designing around now:
- The reset is always a number of seconds, never a timestamp, which removes the clock-skew problem of the legacy headers.
- If a response has both
RateLimitandRetry-After, the draft saysRetry-Aftertakes precedence. - Remaining quota is information, not a promise. The draft states that clients must not assume a positive value guarantees the next request will be served.
How a client should handle a 429
Honour Retry-After first
If the response carries Retry-After, wait at least that long. The server knows when its window resets; the client's own backoff schedule is only a guess. Retrying earlier wastes a request and, on some APIs, extends the penalty.
Put an upper bound on how long you are willing to wait. A Retry-After of an hour in the middle of a user-facing request should become an error shown to the user, not a held connection.
Back off exponentially, with jitter
When there is no Retry-After, or the failure was a network error, 502, 503 or 504, wait longer after each attempt: for example 0.5 seconds, then 1, 2, 4. Cap the delay and the number of attempts.
Then randomise. If a hundred clients are throttled at the same moment and all wait exactly one second, they all return at the same moment and are throttled again. AWS's analysis in Exponential Backoff and Jitter compares strategies and recommends what it calls full jitter: sleep for a random time between zero and the current exponential ceiling. Both helpers below do this.
Retry only what is safe to repeat
A 429 normally means the server rejected the request before doing any work, so repeating it is safe. A timeout or a 502 is different: the request may have been processed and only the response lost. RFC 9110, section 9.2.2 defines which methods are idempotent (GET, HEAD, PUT, DELETE among them) and can be repeated automatically. POST and PATCH are not.
Idempotency keys close that gap. The client generates a unique value, typically a UUID, and sends the same value on every attempt of one logical operation. The server stores the outcome against the key and returns the stored result instead of repeating the work. Stripe's API made the pattern familiar.
The IETF is standardising it in The Idempotency-Key HTTP Header Field. At the time of writing (November 2026) this is also an active working group draft rather than an RFC, at revision 08, dated 22 October 2026. It defines the header as a Structured Fields string:
Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"The draft also recommends how a server should answer misuse: 400 when a required key is missing, 422 when a key is reused with a different payload, and 409 when a retry arrives while the original request is still being processed.
Know when not to retry
Do not retry other 4xx responses; the request itself is wrong and will fail the same way. Check the body of a 429 too. Many APIs use the same status for a per-minute limit and for an exhausted monthly quota, and waiting a few seconds does not help with the second.
A retry helper in JavaScript
This helper wraps fetch. It retries 429, 502, 503, 504 and network errors, prefers Retry-After in either form, and otherwise uses capped exponential backoff with full jitter. After the last attempt it returns the response so the caller can inspect it.
const RETRYABLE = new Set([429, 502, 503, 504])
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
// Retry-After is delay-seconds ("30") or an HTTP-date. Returns milliseconds or null.
function retryAfterMs(response) {
const value = response.headers.get('retry-after')
if (!value) return null
if (/^\d+$/.test(value.trim())) return Number(value) * 1000
const date = Date.parse(value)
return Number.isNaN(date) ? null : Math.max(0, date - Date.now())
}
export async function fetchWithRetry(url, options = {},
{ maxAttempts = 5, baseMs = 500, capMs = 30_000, maxWaitMs = 120_000 } = {}) {
for (let attempt = 1; ; attempt++) {
let response = null
try {
response = await fetch(url, options)
if (!RETRYABLE.has(response.status)) return response
} catch (error) {
if (error.name === 'AbortError' || attempt >= maxAttempts) throw error
}
if (attempt >= maxAttempts) return response
const backoff = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1))
const wait = (response && retryAfterMs(response)) ?? backoff
if (wait > maxWaitMs) return response
await response?.body?.cancel()
await sleep(wait)
}
}Use it for idempotent requests as it stands. For a POST, generate one key before the first attempt and pass it in options.headers, so every attempt carries the same value.
The same helper in Python
The Python version uses the requests library and follows the same rules. parsedate_to_datetime from the standard library handles the HTTP-date form.
import random
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
import requests
RETRYABLE = {429, 502, 503, 504}
def retry_after_seconds(response):
value = response.headers.get("Retry-After")
if not value:
return None
if value.strip().isdigit():
return float(value)
try:
when = parsedate_to_datetime(value)
except (TypeError, ValueError):
return None
return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
def request_with_retry(method, url, *, max_attempts=5, base=0.5, cap=30.0,
max_wait=120.0, **kwargs):
kwargs.setdefault("timeout", 10)
for attempt in range(1, max_attempts + 1):
response = None
try:
response = requests.request(method, url, **kwargs)
if response.status_code not in RETRYABLE:
return response
except (requests.ConnectionError, requests.Timeout):
if attempt == max_attempts:
raise
if attempt == max_attempts:
return response
wait = retry_after_seconds(response) if response is not None else None
if wait is None:
wait = random.uniform(0, min(cap, base * 2 ** (attempt - 1)))
if wait > max_wait:
return response
time.sleep(wait)What a server should return
A throttled response should let a client recover without reading your documentation. Return 429, always with Retry-After in seconds, and a body that says which limit was hit. The Problem Details format in RFC 9457 is a good fit for the body.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 23
RateLimit-Policy: "default";q=100;w=60
RateLimit: "default";r=0;t=23
{"title": "Rate limit exceeded", "status": 429, "detail": "100 requests per minute allowed. Retry in 23 seconds."}Beyond the response itself:
- Send the limit headers on successful responses as well, so clients can slow down before they are refused.
- Use
429for limits tied to the caller and503withRetry-Afterwhen the service as a whole is overloaded. - Give different limits different machine-readable codes, so a client can tell "wait a minute" from "the monthly quota is used up".
- Reject throttled requests before doing expensive work, so that a
429is always safe to retry. - If you accept
Idempotency-Key, document how long keys are kept and what happens on reuse.
APIStack's APIs answer a throttled call this way. Each plan has a per-minute limit: 10 calls on the free plan, 100 on Pro and 500 on Enterprise. A call over the limit gets a 429 with a Retry-After header giving the seconds until the limit resets. The limits and quotas are listed in the rate limits section of the docs, and either helper above handles the response without changes.
Summary
429andRetry-Afterare the only fully standardised parts of rate limiting in HTTP. ParseRetry-Afteras either seconds or an HTTP date, and honour it before any backoff of your own.- The IETF
RateLimitandRateLimit-Policyheaders and theIdempotency-Keyheader are both still Internet-Drafts at the time of writing (November 2026). TheX-RateLimit-*headers remain provider-specific. - Without
Retry-After, use capped exponential backoff with full jitter, and limit the number of attempts and the total wait. - Retry idempotent methods freely. Retry
POSTonly with an idempotency key the server documents, and never retry other4xxerrors. - Servers should send
429withRetry-After, expose limits on successful responses, and distinguish short-term throttling from exhausted quotas.