Common problems

Updated 2026-08-23

I get 404 on every endpoint#

Almost always an extra /api in the URL.

api/ is the server's document root, not part of the public path.

Also check the version: v1 and v2 are retired and return 404. Use v3.1.

The response is HTML, not JSON#

You reached something other than the API — usually a wrong base URL, or a redirect. Check the URL as above. docxtract.rpatech.ai is a legacy alias that redirects; use api.docxtract.io.

The SDKs turn this into a TransportError that names the cause rather than a JSON parse error.

401 with a key I just created#

Check the separator: DocXtract keys use sk_ with an underscore. A hyphen after sk means the key belongs to a different API provider.

If the key is definitely a DocXtract key, check whether it is revoked or past expires_at in the portal. Verify for free:

curl https://api.docxtract.io/v3.1/authorised -H "Authorization: Bearer sk_..."

402 — but my key is valid#

usage_limit_exceeded is not an auth failure. The key is fine and out of credits. Retrying will not help. See rate limits and quotas.

Extraction "worked" but the output is nonsense#

Two likely causes.

You did not set the document type. It defaults to invoice, so a passport sent without a type is extracted as an invoice — a successful 200 full of wrong fields. Always set model or document_type explicitly.

You are reading a chunk manifest as a result. A PDF over 3 pages returns 202 with a list of chunk jobs in data, not extracted fields. Code that checks only success === true will treat that as a result.

429 on a large PDF#

You are firing chunk calls in parallel. The limit is 10 requests per minute, so parallelism produces 429s without finishing sooner. Process chunks sequentially.

410 job_expired#

Multi-page jobs live 2 hours from the split. Past that, the staged chunks are gone and the document must be re-uploaded. If you are hitting this, you are processing chunks too slowly — check whether you are sleeping between calls longer than necessary.

429 too_many_open_jobs#

You have 5 unfinished multi-page jobs, the per-key maximum. Collect or finalize them, or wait for them to expire. Unlike an ordinary 429, waiting out the rate window will not clear this — the outstanding jobs must finish.

Accuracy is lower than expected#

• Confirm you are using the most specific document type available; invoice_detailed beats invoice on complex multi-page invoices
• Check scan quality — skewed, low-contrast, or sub-200-DPI scans hurt every OCR system
• For a document type that is a poor fit, a custom prompt template can be built; contact support

Best practices#

• Set the document type explicitly. Never rely on the invoice default.
• Call models at startup instead of hardcoding type names. It costs no credits.
• Branch on error.code, not the message. Codes are stable; wording is not.
• Keep keys server-side. Never in front-end code.
• Validate locally first. Reject files over 10 MB or of the wrong type before uploading.
• Handle the 202 branch, or use an SDK.
• Treat data as an open map. Prompt templates get revised.
• Budget for extraction_failed being billed on the synchronous path.
• Retry only retryable errors. Input errors, expired jobs, and exhausted credits will never succeed on retry.

Still stuck#

support@docxtract.io. Include the error.code, the HTTP status, the document type, and roughly when it happened — that is usually enough to find the request in our logs. Never send your API key.

Something wrong or missing on this page? Tell us.