What each limit actually does
Why requests/minute is approximate
The gateway throttles per second, not per minute, and it is a token bucket. A 500/minute plan is configured as a refill of ≈8.33 requests/second with a burst capacity of 100. The consequence is arithmetic, not a defect: a client that has been idle arrives with a full bucket, so it can land 100 requests immediately and then draw the sustained rate on top. Inside one rolling minute it can therefore complete meaningfully more than 500 requests. Conversely, a client that sends its whole minute’s allowance in the first two seconds will be throttled even though it is under its per-minute number. Read your per-minute figure as a sustained rate you can plan capacity against, not as a ceiling that will reject the 501st request.Why requests/day is approximate
The gateway’s quota periods areDAY, WEEK and MONTH — there is no finer
period, which is also why requests/minute cannot be expressed as a quota at all.
Quota accounting is distributed and eventually consistent, so the count that
trips is close to your usage rather than identical to it.
Why tokens/minute is “exact accounting, approximate admission”
The token count is computed exactly from your request body, before any engine work. What is approximate is when that count starts refusing traffic: enforcement rides on the same 60-second claim cache as everything else, so there is a bounded window in which you can exceed the rate before admission catches up.Your hard admission controls are the request rate, the daily quota and the
per-request ceiling. Read the tokens/minute figure as the sustained token rate
your plan is sized for.
The one limit that is exact
The per-request ceiling is checked at the top of the handler, before the engine runs and before anything is billable. It is stateless: there is no cache, no window, no eventual consistency. If your request is over it, you get a413
with the exact numbers, every time.
That is deliberate, and it is the control that actually matters against runaway
cost: it bounds what any single request can consume, which is the failure mode
a rate limit cannot bound at all.
The plans
Burst is 20% of the per-minute allowance at every plan, so a plan upgrade never
shrinks your burst headroom.
At the Enterprise plan the per-minute rate is the binding constraint:
2,000/min sustained for a full day is 2,880,000 requests, so the daily quota
cannot be reached. Plan against the rate, not the quota.
Per-request ceilings
These apply to every single request, independently of your plan’s rate.
A
413 from the token or record ceiling tells you exactly what to do about it:
observed/limit pair is there so you can resize precisely
instead of halving and retrying.
What counts toward the 100,000
The same quantity the meter uses — every customer-supplied text field the engine processes:keywords, tags and attributes are not counted — they are structurally
small, and metering them would complicate a number you have to be able to
reproduce for no additional protection.
A size cap on those three fields is specified and is not enforced yet: today
the only thing bounding them is the 6 MB body limit. Do not read “not metered”
as “free to fill” — the cap ships with the meter, and a payload built around
their absence will start being rejected.
The ceiling is denominated in the heuristic token count that this formula
produces, which reads roughly 20–25% under an exact model tokenizer’s count of
the same text. A 100,000 heuristic ceiling therefore admits something in the
region of 125,000–128,000 true tokens. When the exact meter replaces the
heuristic, the published ceiling moves with it in the same change, so the true
ceiling does not silently shift.How to recompute your own bill has the
reference implementation of
estimate_tokens, so you can check a payload
against the ceiling before you send it.Keys per organisation
The cap exists for a specific mechanical reason rather than as a licensing lever: a suspension or plan change has to rewrite the organisation record and every key in one all-or-nothing transaction, and that transaction has a hard size limit. Capping keys is what keeps a plan change atomic. Remember that rotation is create-then-revoke, so you need one spare slot to rotate without an outage.Key operations go through us today. Self-serve minting, rotation and
revocation arrive with the account dashboard; until then, ask and we will do it.
Provisioning a key is not instantaneous either way — associating it with your
plan takes a minute or two.
Handling a 429
A rate limit and a daily quota both surface as429, with different bodies:
Retrying a daily-quota
429 in a tight loop turns one exhausted quota into a
self-inflicted outage plus a support ticket. Branch on the body.
Because the plan limits are approximate in both directions, a 429 is a
normal operating condition rather than an incident. Build the backoff in from
the start; do not treat the first one you see as a bug.
Requesting more
Rate, quota and per-request ceilings are plan attributes, so the usual answer is a plan change. Two cases are worth raising with us directly instead:- A workload that is legitimately over the per-request ceiling — a single document that genuinely does not fit. Splitting is usually the right answer, but not always, and we would rather hear about the case than have you work around it silently.
- A burst shape the token bucket handles badly — for example a batch job that wakes hourly and wants its whole hour’s traffic in ten seconds. That is a configuration conversation, not a plan upgrade.
Errors
Every status code, what causes it, and whether to retry.