The RateLimit Header Everyone Calls "the New Standard" Still Isn't One. Its Latest Review Came Back "Not Ready."

The RateLimit header everyone assumes is finished

Search for API rate-limiting advice published in 2026 and most guides converge on the same recommendation: retire X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and move to the IETF's RateLimit and RateLimit-Policy headers instead. The framing is consistent across guides. New standard, old headers deprecated, migrate now. None of that is quite accurate yet.

It is an easy claim to repeat, because the draft has a working-group name, a version number in double digits, and header syntax that looks finished on the page. What most of those guides skip is checking the actual document status on the IETF datatracker before writing the migration instructions.

The document behind those headers is draft-ietf-httpapi-ratelimit-headers, currently at version 11, published by the IETF HTTPAPI working group on 23 May 2026. It carries Standards Track intent, but it is an Internet-Draft, not an RFC. The IESG has not scheduled it for approval, and an early directorate review of the previous version came back with a verdict of "not ready." That is not a rejection, but it does mean the exact field syntax you would be copying into your API today could still change before this becomes an actual standard.

What the RateLimit header draft actually specifies

The draft defines two response headers, both built on RFC 9651 Structured Field Values rather than the plain integers most vendors use today. RateLimit-Policy describes a quota a server enforces; RateLimit reports what is left against it right now.

Under RateLimit-Policy, q is the quota amount and is required, qu is the unit (requests, content-bytes, or concurrent-requests), and w is the window length in seconds. Under RateLimit, r is the remaining quota and is required, and t is the number of seconds until it resets. Both headers accept an optional pk parameter, a partition key, so a single response can describe more than one limit: a per-user quota and a per-IP quota, say, without every vendor inventing its own extra header for the second one.

# What most APIs send today
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 5000
x-ratelimit-remaining: 0
x-ratelimit-reset: 1772524800
retry-after: 60

# What draft-ietf-httpapi-ratelimit-headers-11 defines
HTTP/1.1 429 Too Many Requests
ratelimit-policy: "default";q=5000;w=3600
ratelimit: "default";r=0;t=45
retry-after: 45

The structured-field syntax itself is settled. RFC 9651 has been finished for a while. It is the RateLimit and RateLimit-Policy fields sitting on top of that syntax, and exactly which parameters they carry, that are still moving.

Six and a half years from proposal to "not ready"

The idea was first presented to the IETF at IETF 106 in Singapore in November 2019, as an individual draft from Roberto Polli at Italy's Team Digitale. The HTTPAPI working group later adopted it, with Alejandro Martinez Ruiz at Red Hat and Darrel Miller at Microsoft joining as co-authors. Version 07 restructured the whole document around structured fields and partition keys. Version 08 added the problem types described below. By 23 May 2026, the working group was on version 11.

The most recent HTTPDIR early review, filed against version 10, flagged issues serious enough to be marked "not ready" rather than cleared toward an IESG telechat. That is an ordinary part of how the IETF vets a Standards Track document, not a crisis for the draft. It does mean the working group is still resolving open questions rather than shipping a finished text.

Nothing in that timeline is unusual for an IETF Standards Track document; plenty of widely used RFCs took a decade or more from first draft to final approval. The mismatch is between that ordinary pace and the confidence with which recent blog posts describe the outcome as settled.

What production APIs send instead

GitHub's REST API is a useful reference point because it is well documented: it returns x-ratelimit-remaining and x-ratelimit-reset on every response, with the reset time as a Unix epoch value in UTC seconds, and falls back to a plain retry-after header for secondary rate limits. None of that matches the draft's syntax, and it does not need to yet.

The draft's own interoperability appendix catalogues exactly the fragmentation this is meant to fix: header names that vary by capitalisation and prefix (X-RateLimit-Limit against X-Rate-Limit-Limit), a "remaining" or "reset" value that means seconds on one API, milliseconds on another, and a full timestamp on a third, and a long tail of vendor-specific parameters that never lined up with each other in the first place.

The three problem types nobody has shipped

Alongside the headers, the draft registers three HTTP problem types for use in a structured 429 or 503 body: quota-exceeded (paired with 429) for a plain policy violation, temporary-reduced-capacity (paired with 503) for a server signalling that it is throttling for its own reasons rather than the client's, and abnormal-usage-detected (paired with 429) for suspicious traffic patterns. Each carries a violated-policies member naming the specific policy that triggered the response.

What to actually ship in your API this year

Keep X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset running for existing clients. Add RateLimit and RateLimit-Policy alongside them rather than instead of them. The cost of sending both is a handful of extra bytes per response, and it lets clients that already understand the structured fields use them without breaking anyone still parsing the old ones.

Log which header pair each client actually reads, if your gateway can do that cheaply. It tells you, months from now, when it is actually safe to drop the legacy headers, instead of guessing from a blog post's migration timeline.

If you are writing a client SDK rather than a server, parse RateLimit and RateLimit-Policy defensively: read the parameters you recognise and ignore the ones you do not, rather than rejecting a response whose parameter set does not match what version 11 defines. That is exactly the kind of change a "not ready" review tends to produce on the next revision.

Retry-After is the one header in this entire area that is not in motion. It was finished years ago as part of RFC 9110, HTTP's core semantics document, and is already implemented almost everywhere. Whatever else changes in the RateLimit draft between now and an eventual RFC number, a client that only trusts Retry-After will not be caught out by it.

That is also the honest answer to how to treat any Internet-Draft cited as if it were finished: read the datatracker entry, not the summary someone wrote about it. A draft can carry a working-group name, a Standards Track label and eleven revisions and still be waiting on its authors to satisfy a reviewer's objections. The version number tells you how much work has gone in. It does not tell you whether the document is done.