Skip to Content
PredictorSDK

What the rate-limit headers actually promise

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