Rate limits & quotas

Limits protect every customer's latency. They come in four kinds, and only the first two ever refuse a request outright.

Your organization's current values are on the console's Settings page.

Request rate

Each key has a token bucket (for example 20 requests per second on standard plans). Every response reports it with the IETF RateLimit headers:

RateLimit-Policy: "default";q=20;w=1
RateLimit: "default";r=17;t=1

q is the quota per window of w seconds; r is what remains and t the seconds until it resets. Over the limit you get 429 rate_limited with Retry-After. Polling counts — prefer webhooks, and use Prefer: wait and If-None-Match to cut requests.

Concurrency (fair scheduling)

Each organization can have a limited number of identification tasks and nutrition tasks running at once. Work above the cap is not rejected: it waits its turn, and the scheduler interleaves organizations so a batch of 10,000 from one customer never starves another customer's single request. Identification and nutrition run on separate queues, so a confirmed analysis's nutrition never waits behind a backlog of new photos.

Quotas and spend caps

• Daily and monthly quotas apply per meter (identification, nutrition). Months are UTC calendar months; days are UTC days.
• When a hard cap is reached, creates return 429 quota_exceeded. A confirm that would start a nutrition run over the nutrition quota also returns 429, and the analysis keeps waiting in requires_confirmation until its deadline.
• An optional monthly spend cap returns 402 spend_limit_reached on create.
• At 80 % and 100 % of a quota we send usage.threshold_reached.
• Usage per day and meter is in the console's Usage page and at GET /v1/usage.

Open confirmations

Manual-mode analyses waiting in requires_confirmation are capped per organization (10,000 by default) so abandoned confirmations cannot grow without bound. Over the cap, creating another manual-mode analysis returns 429 too_many_pending_confirmations. Shorter expires_after windows keep the number down.

Test mode

Test keys are not metered, have no quotas or spend cap, and are still rate-limited.

Service protection

If a dependency we need for metering is unavailable, creates are refused with 503 service_unavailable and Retry-After rather than run unmetered; reads keep working. During planned maintenance, intake returns 503 maintenance. Retry both with the same Idempotency-Key.