Rate limits and quotas

Two limits apply to every authenticated call, and they fail differently on purpose.

Burst: a token bucket

A continuous-refill bucket per tenant and operation class. Emptying it produces:

HTTP 429
code: RATE_LIMITED
retryable: true

It refills. Back off and retry.

Monthly: a fixed cap

A per-calendar-month counter per tenant and class. Exhausting it produces:

HTTP 402
code: TENANT_QUOTA_EXCEEDED
retryable: false

It does not refill before the next period. Retrying will not help; the plan needs to change. This is why it is a 402 and not a 429 — a client that retries on both will hammer an endpoint that cannot succeed.

Operation classes

Class	Covers	Monthly dimension
lookup	Identifier resolution and product reads	Resolutions
evidence	Evidence and passport reads	Evidence reads
search	Search queries	None
export	Tenant data export	None

search and export are burst-limited only.

Plan limits

Plan	Burst capacity	Refill / min	Monthly resolutions	Monthly evidence reads
free	10	10	1 000	500
developer	120	120	50 000	25 000
business	600	600	500 000	unlimited
enterprise	6 000	6 000	unlimited	unlimited

At this revision a plan’s monthly cap is enforced as a hard stop on every tier, including business. There is no metered overage: the service will refuse rather than bill you for usage you did not agree to in advance.

The enterprise burst figure is an infrastructure safety net against a runaway integration, not a commercial commitment.

Headers

Every enforced call carries the burst bucket’s state:

Header	Means
ratelimit-limit	Bucket capacity
ratelimit-remaining	Tokens left
ratelimit-reset	Seconds until the bucket refills
ratelimit-warning	Present, as soft-limit, once fewer than 20% of tokens remain

These headers describe the burst bucket. On a 402 they describe the monthly counter instead, since that is the limit that denied the call.

If the quota subsystem is not reachable, the request is allowed and no headers are emitted at all. Absent headers mean nothing was checked — they never mean an unlimited allowance. Do not treat a missing ratelimit-remaining as headroom.

Both surfaces

REST and MCP share one limiter. A tool call through /v1/mcp and a GET /v1/products/… draw on the same bucket for the same tenant.