Rate limits

Every /api/v1 request that carries a credential passes through one gate, which authenticates the key, checks the route's scope, meters the call and resolves the tenant's mode. There is no route where a keyed client can skip the budget.

Two routes are outside the key gate by design, and both are browser surfaces rather than API calls: GET /api/v1/images/{id} is an <img> tag, and GET /api/v1/stream/prices is an EventSource. Neither can hold a key. Neither is unbounded either. Images are metered per client address at 300 a minute, which is several full catalogue pages inside a minute, and the bytes are cached so a burst does not become one upstream fetch per request. Over that, images answer 429 rate_limited like anything else. The stream caps connections, contracts per connection and total instruments, meters a session that presents one, and still applies an operator's offering policy. A stream at capacity answers 503 stream_capacity with a Retry-After.

That is the whole /api/v1 surface. This table is generated from the OpenAPI document at build time, and CI asserts that every scope in that document is the scope the handler actually passes to the gate, so it cannot list a route that does not serve, omit one that does, or name a scope that is not enforced. The version of this table that was maintained by hand had gone six routes out of date underneath a sentence claiming to be exhaustive.

The second ceiling, and why your headers cannot see 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.

Most responses carry 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. The exceptions are listed below.

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 most of the 429s. It cannot avoid all of them: the headers report the key, the tenant ceiling is counted separately, and two money-moving routes answer without the headers at all. Keep a retry path.
• POST /api/v1/quotes and POST /api/v1/orders do not return the three headers. Both are metered exactly like every other route; they just do not report the window back. Carry your own count between the reads that do.

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.