Rate limits

Response headers

REST responses can report the allowance governing the current request:

X-RateLimit-Limit: <current allowance>
X-RateLimit-Remaining: <remaining allowance>
X-RateLimit-Reset: <reset time in Unix seconds>
X-Request-Id: <request UUID>
Cache-Control: no-store

Use the headers when present rather than assuming a fixed request rate. A key has its own request allowance within the allowance shared by the organization's keys. Other callers can affect the remaining count, and rotating a key does not reset it.

Lookup-row writes also check a row-write allowance. Their headers can describe whichever allowance governs that request. Other API families can use the app's commercial allowances, such as scans or AI assessments, as well as request limits. Permission to call a route does not bypass those allowances.

Retry temporary failures

For 429 rate_limited or 503 service_unavailable, follow Retry-After when returned:

Retry-After: <seconds to wait>

Wait at least that long, add a small random delay, and use exponential backoff when no retry time is supplied. Avoid repeatedly sending all parallel requests again at once. Stop and report a persistent failure.

A read can usually be repeated with the same parameters. For a write, check what completed before trying again and retain the same request key when that operation requires one. A temporary failure does not prove that no work was accepted. Follow writes and retries.

If a pagination cursor expires while waiting, follow that resource's restart rules. For lookup rows, see cursor recovery.

Authentication, Playground, and MCP

Repeated invalid credentials can exhaust an authentication-attempt allowance and return 429 instead of 401. Fix the credential rather than retrying it unchanged.

Playground requests use the signed-in admin session with the key's saved permissions and do not count against the key's request allowance. They still make real changes when you send a write.

MCP clients can also receive temporary busy or unavailable responses before a tool runs. Read the returned failure and retry guidance. For accepted tool work, follow its operation status rather than starting it again.

Ping needs no key and has a separate allowance based on the caller's address. Its headers do not describe a key's remaining requests. The public OpenAPI document needs no key and does not carry rate-limit headers.