Rate limits by endpoint type
Every route of /v1 belongs to one rate class. Limits are per project and class: a burst of
submit calls never uses the read budget. The class of each operation is the
x-dx-rate-class extension of openapi/openapi.json.
| Class | Which endpoints | Default (self-hosted) | trial plan |
|---|---|---|---|
read |
Every GET: lists, details, results, metrics, events, GET /v1/me (key check) |
600 / min | 300 / min |
submit |
Every POST, PUT, PATCH and DELETE: runs, one-shot POST /v1/extract and POST /v1/parse, uploads, workflow and version changes, review actions, API keys |
120 / min | 30 / min |
review |
Reserved for review actions. No route uses it today: they count in submit. |
300 / min | 120 / min |
| (none) | GET /healthz, GET /readyz, GET /v1/status, GET /auth/*, the /.well-known/* key sets |
not limited | not limited |
On top of the class budget:
- Failed authentication: 10 wrong or missing keys per minute per client address, on any route
(policy
auth-failures). The eleventh is429. - Sign-in links (
POST /auth/email/start, self-service sign-up): 5 per email per hour (beyond it the answer stays202and no mail is sent), 20 per client address per hour and 60 per minute for the whole server (429). - Quotas are separate from rates:
max_runs_per_day,max_pages_per_month,max_concurrent_runs,max_queued_runs. They answer429 quota-exceededwithlimit,usedandresets_at. - Waiting (
?wait=N, at most 60 s) holds one request open, but it is one request of its class: it does not use extra budget while it waits. - Size limits (
max_file_mb25,max_files_per_packet,max_pages_per_file) answer413or422, not429.
What a response tells you
Every response of a limited route carries the IETF headers:
RateLimit-Policy: "read";q=600;w=60
RateLimit: "read";r=599;t=1
q is the budget per window w (seconds), r what is left and t the seconds until it is
back. A 429 rate-limited also has Retry-After (seconds). The algorithm is GCRA: a burst of up
to q calls, then one every w/q seconds.
Raising or lowering a limit
Plans live in api/plans.toml (DX_PLAN) and each project can override them
(project_limits.rate_submit_per_min, rate_read_per_min, rate_review_per_min; empty means the
plan default, zero or negative means unlimited). The rate state is kept in the memory of each
replica: with N replicas the effective limit is N times the configured one.
Staying under the limits
- The SDKs (
extractit-sdk,@extractit/sdk) retry408,429and5xxthree times, honouringRetry-After, with oneIdempotency-Keyper call. - Prefer
?wait=Nor a webhook over pollingGET /v1/runs/{id}. extractit runsends at most--concurrencyruns at a time (default 8).- Read lists with
limitand the cursor, not with many small calls.