Handling rate limits

Requests are limited per organization, not per key. Minting a second key does not buy more capacity; it just gives you two ways to spend the same allowance.

The budgets

Each operation belongs to a cost class, because reading a page of products and starting an enrichment run are not the same kind of request.

Class	Burst	Sustained	Applies to
Read	20/s	600/min	Every `GET`
Write	10/s	300/min	Value edits, definitions, views, lists, webhooks
Job	2/s	100/hour	Imports, exports, AI helpers, publish runs
Spend	1/s	20/hour	Enrichment runs and re-enrichment

Burst and sustained are enforced independently: a client may spike briefly and still be held to the longer budget.

The headers

Every response carries the state of the budget it drew on, so you need not hit a 429 to learn where you stand.

RateLimit-Limit: 600
RateLimit-Remaining: 594
RateLimit-Reset: 41

RateLimit-Reset is seconds until the window rolls.

At 429

A 429 adds Retry-After, in seconds. Wait that long — it is the real answer, not an estimate.

{
  "code": "rate_limited",
  "status": 429,
  "title": "Too many requests",
  "detail": "Over the read budget for this organization. Retry in 12s."
}

Retry on 429, 503 and a network failure. Do not retry a 400, 403, 404 or 422: the request will be refused identically next time, and a loop of them counts against the same budget.

Throttling comes before the scope check

A 429 can arrive on a request that would also have failed for permissions. Fix the throttling first, then read what the retry says.