Rate limits and quotas
Updated
Two different ceilings#
These are easy to confuse and behave differently:
| Rate limit | Credit quota | |
|---|---|---|
| Measures | Requests per time window | Pages processed, cumulatively |
| Error | 429 rate_limit_exceeded | 402 usage_limit_exceeded |
| Resets | Automatically, per window | Never — needs topping up |
| Retry helps? | Yes, after waiting | No |
Rate limits#
Defaults per key:
| Window | Requests |
|---|---|
| Per minute | 10 |
| Per hour | 100 |
| Per day | 1,000 |
| Per month | 10,000 |
Every response carries your current position:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the window |
X-RateLimit-Remaining | Requests left |
X-RateLimit-Reset | Unix timestamp when the window resets |
429, wait until X-RateLimit-Reset rather than guessing a backoff. The
official SDKs do this automatically and fall back to exponential backoff only when the
header is absent.The 10-per-minute limit shapes multi-page design#
A 50-page PDF splits into roughly 17 chunks, each needing its own process call. At 10 requests per minute that is about two minutes of wall clock regardless of concurrency — so firing chunks in parallel does not finish sooner, it just produces 429s.
This is why all three official SDKs process chunks sequentially. Do the same in a hand-rolled integration.
Credits#
Billing is per page, not per request: a 10-page document costs 10 credits.
422 extraction_failed) on the synchronous path still
deducts 1 credit. Budget for it when reconciling usage. On the multi-page path a failed
chunk is not charged and stays available for retry, and persist_failed never charges.Two quota errors exist:
| Code | HTTP | Meaning |
|---|---|---|
usage_limit_exceeded | 402 | The key's cumulative cap is reached |
insufficient_credits | 402 | Remaining credits do not cover this document's page count |
insufficient_credits is checked before a large document is split, so you are told up front rather than part-way through.
Document limits#
| Limit | Value |
|---|---|
| Max file size | 10 MB (413 file_too_large) |
| Max pages | 150 (400 page_limit_exceeded) |
| Accepted types | PDF, JPG, PNG (400 invalid_file_type) |
| Sync threshold | 3 pages — above this a PDF is split |
The SDKs check size and type locally before sending, so a bad file costs no round trip.
Multi-page job limits#
| Limit | Value |
|---|---|
| Job TTL | 2 hours from split (410 job_expired) |
| Concurrent open jobs per key | 5 (429 too_many_open_jobs) |
| Pages per chunk | 3 |
too_many_open_jobs means you have unfinished splits. Collect or finalize them, or let them expire, before starting more. It arrives as a 429 but waiting alone will not clear it within the window — you need to finish the outstanding jobs.
Raising limits#
Rate limits and credit caps are set per key. Contact support@docxtract.io if your volume needs more than the defaults.
Something wrong or missing on this page? Tell us.