Skip to content

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 is 429.
  • Sign-in links (POST /auth/email/start, self-service sign-up): 5 per email per hour (beyond it the answer stays 202 and 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 answer 429 quota-exceeded with limit, used and resets_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_mb 25, max_files_per_packet, max_pages_per_file) answer 413 or 422, not 429.

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) retry 408, 429 and 5xx three times, honouring Retry-After, with one Idempotency-Key per call.
  • Prefer ?wait=N or a webhook over polling GET /v1/runs/{id}.
  • extractit run sends at most --concurrency runs at a time (default 8).
  • Read lists with limit and the cursor, not with many small calls.