RateLimit and RateLimit-Policy versus X-RateLimit-*: reading whichever quota headers an API sends

What it is

RFC 9110 defines one standardised, load-bearing header for this purpose: "the Retry-After field value can be either an HTTP-date or a number of seconds to delay after receiving the response," formally Retry-After = HTTP-date / delay-seconds. RFC 9110 describes its meaning on 503 and 3xx responses, and RFC 6585 lets a 429 include it. It states how long the client "ought to wait" — the server's own number, not a client-side estimate. Separately, an active IETF Internet-Draft, draft-ietf-httpapi-ratelimit-headers (revision -11 at the time of writing), proposes two advisory fields for use before a request is throttled: RateLimit-Policy, describing the quota (for example RateLimit-Policy: "default";q=100;w=60, meaning 100 requests per 60-second window under a policy named "default"), and RateLimit, reporting the currently available quota under that policy (for example RateLimit: "default";r=50;t=30: 50 quota units available, to be used within an effective window of 30 seconds). The draft warns that the effective window "does not imply anything about when the server will increase the available quota", so t is not a reset timestamp. This is still a draft — an Internet-Draft is, by IETF process, "valid for a maximum of six months" and inappropriate to cite as a stable reference — so its exact field syntax can still change before publication. In practice, most production APIs predate or ignore this draft and instead send their own headers with names like x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (GitHub's REST API is one documented example), in a shape the draft does not govern and that varies by vendor.

Why it matters

A generic client integrating with many APIs will encounter all three situations — a standards-track advisory header, a vendor-specific ad hoc header, or nothing but Retry-After on the eventual 429 — and needs a fallback order that does not assume any of them are present.

How to apply

• Treat Retry-After as authoritative whenever present, on any status code that carries it; parse both forms (integer seconds and an HTTP-date) and wait at least that long before retrying.
• If RateLimit/RateLimit-Policy are present, parse them defensively (they are a draft: field names, delimiters and even the header names have changed across draft revisions) and use them to slow down before the quota reaches zero.
• If only vendor-specific x-ratelimit-*-style headers appear, treat their presence and meaning as specific to that API — do not assume the same field names mean the same thing on a different provider.
• When none of the above appear, fall back to exponential backoff with jitter on 429/503, since RFC 9110 does not require any advisory header at all.

Pitfalls

Hard-coding a parser for the current draft syntax of RateLimit/RateLimit-Policy and treating it as a finished standard; the draft explicitly warns against citing it "as reference material... other than as work in progress." Ignoring a Retry-After value because an advisory header suggested more quota remained — Retry-After reflects what the server actually decided, which can differ from an advisory estimate sent earlier.