What the rate-limit headers actually promise
X-RateLimit-Remaining does not count down. Across strictly sequential
requests inside one X-RateLimit-Reset window it repeats values, skips them,
and goes back up — measured on 2026-08-26 against a 1000 req/min key, 120
sequential requests over three windows produced 42 increases, the largest
+8. A client that slowed down as the number fell was reading a signal that
sometimes rose while it was spending.
Nothing about the numbers changed, because nothing about them is wrong. What
changed is what we say they mean, in openapi.yaml and in the guides.
The budget recovers continuously, not at a boundary. This is the piece that
made the old documentation misleading. X-RateLimit-Reset was described as
"when the current window resets", which invites the obvious model: spend
X-RateLimit-Limit requests, wait for the reset, get a fresh allowance. That is
not what happens. Four boundary crossings measured on the same day moved the
reported budget by +5, 0, +2 and +2 — never a step back to the limit. Earlier
requests age out gradually, which is also why X-RateLimit-Remaining can rise
while you are consuming it.
X-RateLimit-Remaining is now documented as advisory, with the measured
spread and the direction of the error: it runs ahead of your consumption, and
by the end of a fast burst it over-stated the true remaining budget by up to 44
requests. The gap widens the faster you send, so it is least accurate exactly
when a caller would consult it. Treat a low value as a reason to slow down;
never treat a high one as permission to burst.
Pace from X-RateLimit-Limit instead, which equals the rate_limit_per_min
already published for your plan on GET /v1/plans. Keep your own timestamps for
a rolling 60 seconds, or just space requests 60 / limit apart, and back off on
429. The 429 and its Retry-After are the authoritative signals; they are
computed from the limiter's own window instant and never disagree with
X-RateLimit-Reset. The
Error Handling guide has the
recipe.
We deliberately did not smooth the header. Clamping it to a monotonic minimum would publish a number the rate limiter never reported, in a header whose name promises the limiter's own accounting — the same kind of invention this API refuses elsewhere when it leaves a venue's figure null rather than computing a plausible one.
Also clarified: unauthenticated routes carry none of these headers, because the
limiter is only consulted once an API key has been read. That covers
GET /v1/plans and the router's own 404 and 405.