API / Errors & limits
Errors & limits
What the service accepts, how long it takes, and how failures are reported.
Error codes
Every error is { "detail": "message" } with an HTTP status.
| Code | Meaning | What to do |
|---|---|---|
400 | Bad request (unreachable source_url / callback_url) | Fix the input. |
401 | Missing or invalid API key | Check your key. |
413 | File too large | Shrink the file below the size limit. |
415 | Unsupported format | Send a supported format. |
422 | Could not read the document | Re-export as PDF. |
429 | Sending too fast | Back off; batch via /v1/jobs. |
5xx | Transient processing error | Retry with backoff — accepted jobs are never lost. |
Limits
| Value | |
|---|---|
| Max file size | 20 MB |
| Pages read | First 10 (longer documents are truncated, not rejected) |
| Formats | PDF, DOCX, DOC, RTF, ODT, PNG, JPG, WEBP, TXT, TEX |
Each page is rendered and read individually, so only the first 10 pages are read —
that covers essentially every CV. A longer document is not rejected: the first 10 pages
are processed and the rest are ignored, and the response metadata flags this with
truncated and pages_total. Oversized
pages are downscaled automatically rather than rejected.
Timing
| Call | Warm | First call after idle |
|---|---|---|
/v1/autofill | <1 s digital · ~3–6 s scanned | same — never waits for the OCR engine |
/v1/parse | ~5 s (1–2 pages) | + warm-up outside business hours (bounded by an automatic failover) |
/v1/extract | ~5–10 s | ~5–10 s (managed — no warm-up) |
/v1/parse-extract | ~10–25 s | as /v1/parse |
To hide the warm-up, call POST /v1/warmup the moment a user
starts (for example, when they pick a file).
Data handling
/v1/parseand/v1/extractstore nothing — they process in memory and return.- For
/v1/jobs, the uploaded document is kept 24 hours and the result 7 days, then deleted. - Logs are retained 30 days with emails and phone numbers redacted.