Skip to main content
LeoNex News

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

Illustration: 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.

Key points

More in Software Engineering

Illustration: Rust in CPython? Discussion at the Python Language Summit
SOFT-ENG Software Engineering

Rust in CPython? Discussion at the Python Language Summit

David Hewitt, representing the Rust for CPython project team, returned to the Python Language Summit to ask Python's core developers what they want from Rust. He presented a phased roadmap, success criteria and a proposal to start with an optional Rust backend for the zlib module. The long-term goal is to make Rust…

6 min read

Illustration: Notable V8 changes from Node.js 26 to 27
SOFT-ENG Software Engineering

Notable V8 changes from Node.js 26 to 27

The Node.js 27 Alpha upgrades V8 to version 15.6, up from 14.6 in Node.js 26. The upgrade brings several new JavaScript language features, a number of behavior changes, performance improvements and memory adjustments. Some changes may break code that relies on the old behavior, so developers should…

3 min read

Email newsletter

Receive a selection of new LeoNex News articles by email.

We only use this address to send the newsletter.

Receive a selection of new LeoNex News articles by email. You will receive a confirmation email; the subscription only takes effect after you confirm. Every email includes an unsubscribe link. Read the privacy policy