429, Retry-After and rate-limit headers

API design: REST, HTTP, GraphQL and gRPC Junior Python 3.13+ PostgreSQL 17+ Reviewed 31 Oct 2026 By Best Latest Apps

Pick the fix

A client gets 429 with Retry-After: 30. What should it do?

OptionsWait at least 30 s (plus a little jitter) before retrying, and slow its request rateRetry immediately with exponential backoff starting at 100 msSwitch to another API keyTreat it as a permanent failure

Hint 1 of 1

The server already told you when.

Choose an answer, then open Show answer below to check it.

Show answer

Answer: A Wait at least 30 s (plus a little jitter) before retrying, and slow its request rate

Correct. That's what the server asked for.

Retry-After is the server telling the client when capacity comes back. Waiting at least that long, with jitter so clients don't return together, gets the request through sooner than hammering.

Why not the others?

B Retry immediately with exponential backoff starting at 100 ms. Ignores the server's explicit instruction.
C Switch to another API key. Evades the limit; often against the terms.
D Treat it as a permanent failure. 429 is temporary by definition.

30-second answer

Return 429 Too Many Requests with a Retry-After header (seconds or a date) and a Problem Details body. Advertise the limits so well-behaved clients can pace themselves: many APIs send RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset style headers (an IETF draft standardises RateLimit and RateLimit-Policy). Clients should wait at least Retry-After, add jitter, and slow down before hitting the limit.

Practise saying it · 30 s. No recording, just a timer

How do you signal rate limits?

Say your answer out loud, then check which of these points you covered:

429 + Retry-After
Problem body
RateLimit headers
Clients wait and pace
503 for global overload

Deep dive

Use 503 with Retry-After when the whole service is overloaded, not a per-client limit.

Return limits per key in docs; different endpoints can have different budgets.

Decide whether rejected requests count against the budget; many APIs don't count them, so a client stuck in a retry loop can recover.

Clients should centralise retry logic so every call obeys Retry-After.

Common mistakes

429 without Retry-After.
Clients retrying immediately in a loop.
Using 403 for rate limits.

Senior take & follow-ups

Name the code and headers, and the client behaviour: wait, jitter, pace.

Follow-up questions

Think of your answer first, then open the hint.

429 or 503?
Show hint
429 for this client's quota; 503 for overall overload.
What if Retry-After is a date?
Show hint
Wait until then; it's an HTTP-date, not seconds.

Similar on iOS: Rate limits and temporary outages The iOS page is the client reacting to 429; here the server decides the limit and the headers.

Suggest a fix if something here is wrong or out of date.