Rate limits
Write the client against the headers, not against a number
Quotas differ by plan and change over time. The policy shape does not: read the headers, back off with jitter, and use the bulk path for bulk work.
- Applied per
- Organisation
- Signalled by
- Response headers
- Resolution
- Metered separately
Definition
How are API rate limits applied?
Limits are applied per organisation and per endpoint class, and communicated on every response through headers giving the limit, the remaining allowance and the reset time. Public passport resolution is metered separately from your account quota, because a scan burst must not consume an issuing pipeline's budget.
A client written against the headers keeps working when a quota changes. A client written against a number from a documentation page does not, and fails at the least convenient moment.
Classes
Not all endpoints are metered alike
| Class | Example | How it is governed |
|---|---|---|
| Public resolution | A consumer scanning a data carrier | Caching and edge capacity, not your quota |
| Read | Fetching a passport or an object history | Account quota, generous, cache-friendly |
| Write | Issuing a passport, appending an event | Account quota, lower ceiling than read |
| Bulk | Back catalogue import, historic event backfill | Asynchronous job with its own concurrency limit |
| Credential operations | Issuing or verifying a signed claim | Metered separately; cryptographic work is not free |
Headers
What every response tells you
RateLimit-Limit: the ceiling for this endpoint class
RateLimit-Remaining: what is left in the current window
RateLimit-Reset: seconds until the window resets
Retry-After: present on 429 — honour this first
# Back off with jitter. A fixed interval across many workers
# turns one brief limit into a sustained one.
const delay = Math.min(2 ** attempt * base, ceiling);
await sleep(delay * (0.5 + Math.random() / 2));Client design
What a well-behaved client does
Reads the headers
Adapts to the current allowance instead of assuming a documented figure.
Backs off with jitter
Randomised delay, so parallel workers do not retry in lockstep.
Uses the bulk path
Back catalogue work goes through bulk, not a loop over a single-resource endpoint.
Separates the pipelines
Issuing and reporting on different keys, so one cannot starve the other.
Caps its retries
Gives up and surfaces the failure rather than retrying indefinitely.
Warns before the ceiling
Alerts on remaining allowance, so the first sign is not a production 429.
Answers
Frequently asked questions
What are the actual limits?
They depend on your plan and on the endpoint class, and they are stated in your agreement rather than here. A published number would be out of date within a release, and an integrator who sized against it would discover the real limit in production. Read the headers instead — they are always current.
How should a client react to a 429?
Honour `Retry-After` if present, otherwise back off exponentially with jitter, and cap the number of attempts. Retrying immediately, or on a fixed interval across many workers, converts a brief limit into a sustained one — the thundering herd that turns a small problem into an outage.
Is public passport resolution rate limited the same way?
No. Resolution is public, cacheable and expected to be bursty, so it is governed by caching and edge capacity rather than by your account quota. A product going viral should not consume the quota your issuing pipeline depends on, which is why the two paths are metered separately.
How should we load a large back catalogue?
Through the bulk import path rather than by looping the single-resource endpoint. Bulk is designed for throughput and runs asynchronously with a job you poll; the per-resource endpoint is designed for latency. Using the wrong one is the most common cause of self-inflicted rate limiting.
Do limits apply per key or per organisation?
Per organisation, with visibility per key. That matters when you scope keys per service: one misbehaving service can consume the shared budget, and the per-key breakdown is how you find it quickly rather than by elimination.
Next step
Tell us your volumes before you build
Catalogue size, issue rate and the seasonal peak. We would rather size the plan correctly than have you discover a ceiling in production.