What to return when rate limited (HTTP 429): Retry-After, RateLimit headers and quotas

In this article
The 429 status code alone tells a client very little. What decides whether the client can recover on its own is what comes with it: the Retry-After value, the RateLimit field pair, and a body that says which limit was hit. This article covers only the response: what to put in it and what the client should do with it, not how to count requests.
What 429 promises and how to write Retry-After
RFC 6585 defines 429 in just a few sentences: the response should include details explaining the condition, and may include a Retry-After header indicating how long to wait. The document does not specify how the server identifies users or counts requests. So the status code states neither the reason nor how long to wait.
RateLimit-Policy and RateLimit help clients slow down before being rejected
Retry-After only speaks about the past: you have been rejected, come back later. The IETF draft on rate limit headers, draft-ietf-httpapi-ratelimit-headers, adds two fields that help clients slow down before being rejected. Version -11, published on May 23, 2026, is still the latest at the time of writing and is still only a draft, not an RFC.
RateLimit-Policy describes the policy: a quota q per window of w seconds.
RateLimit reports the client's current position: r units remain, and t is the number of seconds within which the client can use at most r.
A token bucket does not map perfectly onto the model of q per w seconds. The author sends the bucket size as q and the time to refill from empty as w. For an exhausted bucket, t is the time until one token is available, and that figure is exact. For a bucket that still has tokens there is no exact answer because it keeps refilling while the client consumes, so t is the time until full; a client that treats r as what it can spend immediately will be safe.
Rate limits and quotas need two different answers
A rate limit is about speed and recovers on its own within seconds, so retrying is correct. A quota is about volume within a billing period, for example 1,000 requests per month on the free plan. Retrying after the quota runs out is pointless until the period ends, or until the customer upgrades or buys more credit. Each situation should have its own status code or error code so the client can tell them apart without guessing.
Hit the rate limit: return 429, Retry-After is the number of seconds until a token is available again, error rate_limited.
Plan quota exhausted at a hard-stop limit: return 429, Retry-After is the number of seconds until the period ends, error quota_exceeded with resets_at in the demo.
Prepaid credit exhausted: return 402, no Retry-After because waiting is pointless, error insufficient_credits.
Customer suspended: return 403, no Retry-After, error consumer_suspended.
Quota service unreachable and the choice was to reject rather than let requests through: return 503, the client applies its backoff, error quota_unavailable.
As for whether to put the monthly quota in RateLimit-Policy, the draft allows it, but the author does not. A quota resets at a fixed moment, and the draft itself warns in section 8.5 that a fixed reset time makes every blocked client come back at the same moment. So the quota response uses Retry-After plus resets_at in the body, and the client treats it as a business event, not a retry.
Order of checks and the client side
The order of checks matters too: the server checks quota before the rate limit. If a customer has used up the month and is also sending too fast, the quota is the reason they need to hear; an answer saying wait 1 second only pushes them into a loop that ends at the quota. Only successful responses consume quota or credit, and a rejected request takes no token from the bucket.
On the client side, the next part of the article points toward the principle of retrying when the wait is short and stopping when the wait is long. The provided text stops right at this heading, so there are no further details to present.


