Errors
The error envelope, statuses and rate limits of the document routes.
The document routes use Drex's error envelope with two extra fields, code and retryable:
{
"error": {
"type": "invalid_request_error",
"code": "invalid_source",
"message": "source.type must be \"url\" or \"parse_result\"",
"retryable": false
},
"request_id": "req_0123456789abcdef0123456789abcdef"
}type is the class to branch on. code is the exact cause: Drex's own, or the document service's code when it refused the request (for example invalid_request, unsupported_file_type or job_not_cancellable), with its detail when it has one. retryable says whether the same request can succeed later; retry creates with the same Idempotency-Key.
| Status | type | When |
|---|---|---|
| 401 | authentication_error | Missing or invalid API key. |
| 402 | insufficient_credit | A create while the balance is not positive and no card pays for usage beyond it. |
| 402 | payment_required | A create while the account has an unpaid invoice. Pay it on the Billing page; not retryable until it is paid. |
| 404 | not_found_error | No such job or saved schema for this account. |
| 409 | conflict_error | Idempotency-Key reused with a different body, or the job can't be cancelled. |
| 410 | not_found_error | A result or file that has expired (result_expired), or a job created before 3 October 2026 whose results are no longer available (job_unavailable). |
| 413, 422 | invalid_request_error | Body too large, not JSON, an invalid_source, or refused by the document service. |
| 429 | rate_limit_error | Over the per-minute limit. Wait retry-after seconds. |
| 502, 504 | upstream_error | The document service refused Drex's own request (ndi_refused_drex) or timed out. Retry later. |
| 503 | service_unavailable | Billing not configured, the job is not confirmed yet (job_pending; retry with the same key), or the document service is down. |
| 529 | overloaded | The API is paused, or Drex's rate limiter is unreachable. Retry after retry-after seconds. |
Rate limits
The document routes have their own requests-per-minute counter per account, at your tier's RPM (see Limits), so polling never uses up your evaluation budget. Downloads of job files don't count. The document service may also throttle an account; that also answers 429 rate_limit_error with retry-after.
A create refused with 429 starts no job and is not billed, and nothing creates it for you later: retry it yourself, with the same Idempotency-Key, within 13 minutes. A later retry of that key answers 503 job_pending until Drex has confirmed with the document service that no job exists under it, then 422 job_not_created; send the job again under a new key. If the document service did start the job after all, it is linked to your request and billed once, like any other.
A create body is at most 1,000,000 bytes, and wait_seconds is capped at 60.