Rate limits

Every route under /v1 shares one limit — /livez and /readyz sit outside it, so an orchestrator's health check can never trip a client-facing limit.

The numbers#

One token replenished every 500ms — 2 requests per second sustained — with room for a 30-request burst. That is generous enough for a dashboard's normal polling, or paginating through a large list in one go, and tight enough to cut off a flood. It is a starting point rather than a measured figure, and deployments can override it.

Hitting it#

A request over the limit gets 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 2

{
  "error": "rate_limited",
  "message": "too many requests; retry after 2s"
}

Retry-After is in seconds — wait at least that long before your next request. There are no X-RateLimit-Remaining or X-RateLimit-Reset headers on a normal, successful response today: the only signal you get about your standing against the limit is the 429 itself, so back off on the first one rather than trying to infer headroom in advance.

Backing off well#

• Retry a 429 after Retry-After has elapsed, not immediately — a request sent before then only extends the wait.
• If you are about to paginate through a large collection, prefer larger per_page values (up to the cap of 100 — see Errors, pagination and versioning) over many small pages; fewer requests for the same data costs you nothing against this limit.
• Prefer live updates to polling on a fixed interval wherever you can — an SSE connection that sits open uses one request, not one every few seconds.

From here, the interactive reference is the fastest way to look up a specific endpoint's exact limits and shape, and the how-to guides walk through using this API for a specific job end to end.