# What the rate-limit headers actually promise (https://docs.predictorsdk.com/changelog/2026-08-26-rate-limit-header-contract)

2026-08-26 · Fix

`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](https://docs.predictorsdk.com/guides/error-handling#building-a-local-limiter) 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`.