Rate limits

Every /api/v1 request passes through one gate, which authenticates the key, checks the route's scope, meters the call and resolves the tenant's mode. Nothing is exempt, so there is no route where a client can skip the budget.

That is the whole /api/v1 surface — eighteen paths, nineteen operations. Nothing else exists on it.

Scope is checked before the limit is consumed

A caller with the wrong scope has made a mistake that no amount of waiting fixes. Charging them a request to say so would turn the 403 into a 429 on the retry, which reads as an entirely different bug and sends whoever is debugging it to this page instead of to their key configuration.

Why the count lives in the database

A per-process counter multiplies the real limit by however many instances are running, which is a limit in name only. A single upsert returning the new count also means two concurrent requests cannot both read the same number and both decide they were under.

A fixed window admits a burst

Twice the allowance can pass across a window boundary. That is a known and accepted property: this protects the service from a runaway loop, not from an adversary. Do not design around the burst — it is not a feature and the window shape may change.

Every response carries the current window on three headers — a success as much as a refusal — so a client can slow down before it is refused rather than discovering the budget by hitting it.

RateLimit-Limit: 120
RateLimit-Remaining: 96
RateLimit-Reset: 37

When the allowance is spent the request is refused with 429, a Retry-After header, and a body that repeats the wait in seconds:

{
  "error": "rate_limited",
  "message": "Over 120 requests per minute for this key.",
  "retryAfterSeconds": 37
}

• RateLimit-Limit: the allowance for this key, this window.
• RateLimit-Remaining: floored at zero, so it never goes negative on a burst.
• RateLimit-Reset, Retry-After and retryAfterSeconds: seconds until the window rolls. Sleep that long, not a fixed guess.
• Read the headers on successful responses too. Backing off as RateLimit-Remaining approaches zero is how you avoid the 429 entirely.

The SDK raises a RateLimitError carrying retryAfterSeconds, so the wait is already parsed for you.

Most integrations that hit a limit are doing one of four things.