Pick the status code
|
Malformed request: bad JSON, a missing field. Resending it unchanged gets the same answer |
|
No key, unknown key, revoked key. RFC 9110 requires a WWW-Authenticate
field on a 401, e.g. WWW-Authenticate: Bearer
|
|
Prepaid credits ran out. The spec still reserves 402 "for future use", so say why in the body |
|
The key is valid but this customer may not do this: account suspended, endpoint not on their plan |
|
Over a rate limit or a quota (RFC 6585). Send Retry-After
when you know when a retry can work |
|
Your side can't serve the request: overloaded, or a dependency is down. Retry-After
works here too |
401, 402, 403: the customer fixes something before retrying. 429: check the error code and any Retry-After
. 503: the problem is on your side. |
What a 429 should carry
|
If present, wait this long before retrying. Seconds or an HTTP date (see Retry-After: two formats) |
|
Each limit: q
= quota, w
= window in seconds |
|
Each limit now: r
= available quota, t
(optional) = how many seconds that quota applies for |
Body |
A stable error code, e.g. rate_limited
, plus retry_after
(see Example 429). Human-readable text is optional |
Content-Type |
application/json
as in Example 429, or an RFC 9457 Problem Details body: application/
problem+json
|
2xx responses |
You can send the RateLimit
fields on success too, so clients slow down before they run out |
RateLimit-Policy
and RateLimit
come from the IETF draft draft-ietf-httpapi-ratelimit-headers. The examples use draft-11. Draft-12 (November 2026) uses a
for available quota and w
for the window in RateLimit
; RateLimit-Policy
keeps q
and w
. Check which draft your clients support. Draft-06 and earlier used RateLimit-Limit
, RateLimit-Remaining
and RateLimit-Reset
. Non-standard X-RateLimit-*
headers vary by API: Reset
can be seconds left or a Unix timestamp.
Example 429
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
RateLimit-Policy: "per_second";q=10;w=1
RateLimit-Policy: "per_minute";q=300;w=60
RateLimit: "per_second";r=0;t=1
RateLimit: "per_minute";r=212;t=18
{"error": "rate_limited", "retry_after": 1}
|
UsageRail's example, draft-11 syntax. Each field can also be sent as one line with the two limits comma-separated. The per-second bucket is empty. The per-minute bucket has 212 of 300 tokens; here t=18
is how long it takes to refill if no more requests arrive.
Retry-After: two formats
Delay |
Retry-After: 120
Whole seconds, a non-negative integer |
HTTP date |
Retry-After:
Sat, 21 Nov 2026 07:00:00 GMT
IMF-fixdate, always GMT |
Servers |
Send seconds. A date depends on the client's clock agreeing with yours |
Round up |
Math.ceil
. Rounding down sends the client back a moment early, into another 429 |
Clients |
Parse both. For a date, wait until that time; if it's already past, wait 0 |
Where it's used |
503 and 3xx (RFC 9110, section 10.2.3), and 429 (RFC 6585) |
Two kinds of 429
| |
Rate limit |
Quota used up |
Window |
e.g. a second or a minute |
e.g. a billing period |
|
e.g. 1–60 s |
If supplied, seconds until reset, e.g. 86400
|
Example code |
|
|
Client should |
Back off and retry |
Stop, tell the user, upgrade or wait |
A 429 alone can mean "wait a second" or "come back next month". I work on UsageRail; its Node SDK puts the reason in an error
field: rate_limited
or quota_exceeded
on a 429, insufficient_credits
on a 402.
|
|
Client retry rules
1. If you retry, wait at least as long as Retry-After
says. It takes precedence over the RateLimit
window. |
2. Safe to retry and no Retry-After
: exponential backoff with full jitter. sleep = random(0,
min(cap, base × 2^attempt))
|
3. e.g. base 0.5 s, cap 30 s, give up after 5 attempts. |
4. Jitter matters. Clients that hit the limit together otherwise retry together and hit it again. |
5. Retry 429 rate_limited
, 502, 503, 504 and dropped connections for idempotent requests (GET, PUT, DELETE). A POST only if the server honours an idempotency key, resent with the same key. |
6. No automatic retries on 400, 401, 402, 403, 404, 422. Send it again once the cause is fixed: a refreshed token, topped-up credits, a resource that now exists. |
7. On quota_exceeded
, stop automatic retries. Show the reset time if the API provides one. |
8. Every retry is a new request, and the API may count it against your limit or bill it. |
Per-customer vs global limits
Per-customer |
One bucket per customer. A noisy customer runs out of their own allowance, not everyone's |
Global |
One bucket for the whole API. Protects your servers, does nothing for fairness |
Key on |
The customer behind the API key, after authentication. Not the IP: customers behind one NAT share an IP |
Before auth |
A coarse per-IP limit is fine for unauthenticated routes (sign-up, key creation) |
Token bucket |
Capacity sets the largest burst; the refill rate sets sustained traffic. For 10 requests/s, refill a token every 100 ms; a capacity of 10 allows a burst of 10 |
Several servers |
In-memory buckets count per process. With 4 servers at 10/s each, one customer whose traffic is spread evenly gets up to 40/s. Split the limit across servers or use a shared counter |
Restarts |
In-memory buckets start full after a deploy: expect one extra burst |
The per-customer API rate limiting docs explain the two-bucket 429 from Example 429 and why a 10/s limit split across four servers can still let about 12/s through. |
When the limiter is down
Applies when the limit check is a network call (a shared counter store, a rate limit service). |
Timeout |
Short, e.g. 500 ms. Every checked request waits for the limiter |
Fail open |
Serve the request without a limit decision. It may go over the limit or go uncounted |
Fail closed |
Answer 503, with Retry-After
if you can estimate recovery. Nothing unchecked is served, and the limiter's outage becomes your customers' outage |
Choosing |
Open for cheap reads your backend can absorb. Closed if one unchecked call can run up a bill |
Don't retry the check |
A check that timed out may already have been counted. If the retry is allowed too, both count |
Limiter says 400 or 401 |
Your config is wrong (bad app key, bad parameter). Log it and answer 500; don't pass a 401 to your customer |
Log every fail-open, so you know how much went through unchecked. |
Minimal 429 in Express
// Per-customer token bucket. Runs after authenticate
// has set req.customerId. In memory, per process.
const CAPACITY = 10; // burst size
const REFILL_PER_SEC = 1; // steady rate
const buckets = new Map();
function rateLimit(req, res, next) {
const now = performance.now() / 1000;
const bucket = buckets.get(req.customerId)
?? { tokens: CAPACITY, updatedAt: now };
bucket.tokens = Math.min(CAPACITY, bucket.tokens
+ (now - bucket.updatedAt) * REFILL_PER_SEC);
bucket.updatedAt = now;
buckets.set(req.customerId, bucket);
if (bucket.tokens < 1) {
const wait = Math.ceil(
(1 - bucket.tokens) / REFILL_PER_SEC);
res.set('Retry-After', String(wait));
return res.status(429).json(
{ error: 'rate_limited', retry_after: wait });
}
bucket.tokens -= 1;
next();
}
app.use(authenticate, rateLimit);
|
Behind a test route that returns 200: send 11 requests from one customer within a second and the 11th gets 429 with Retry-After: 1
, while a second customer still gets 200. performance.now()
is monotonic, so a wall-clock jump can't refill every bucket at once.
|
Created By
Metadata
Comments
No comments yet. Add yours below!
Add a Comment
Related Cheat Sheets
More Cheat Sheets by SuperLede