Support
Troubleshooting
Most failures are actionable before you retry. Reuse the same Idempotency-Key only when replaying the exact same logical request after a timeout or transport error.
Support
Parse
Parse And Resume Failures
| Code | Fix |
|---|---|
invalid_pdf | Confirm the upload is a real PDF. The gateway checks magic bytes, not the extension. |
corrupt_pdf | Re-export or repair the file, then resubmit. |
password_protected | Decrypt the PDF before uploading. Password submission is not part of this lane. |
ocr_required | Run OCR upstream, then resubmit the text-native PDF. |
invalid_page_range | Use a selector like 1-3,5 that resolves inside the document bounds. |
page_limit_exceeded | Narrow page_range or move to a plan with a higher parse cap. |
Output quality
The Job Succeeded But The Output Is Wrong
| Symptom | Try |
|---|---|
| Text in the wrong order | reading_order=off for less reconstruction, reading_order=xycut for more. |
| Tables missing cell groupings | table_method=cluster. |
| Headings and sections not detected | use_struct_tree=true if the PDF is tagged. |
| Line breaks collapsed | keep_line_breaks=true. |
| Page headers and footers missing | include_header_footer=true. |
| Figures missing from Markdown | formats=markdown_with_images. |
Batch
Batch Download States
| Status | Code | Meaning |
|---|---|---|
| 400 | — | The requested format was never requested for this batch. |
| 425 | batch_not_ready | The batch or file has not reached a terminal state yet. |
| 409 | batch_file_failed | That file failed after enqueue. Other files may still download. |
| 410 | output_expired | The one-hour artifact TTL has passed. |
Transient
Capacity And Retries
server_busyandbackend_unavailableare temporary. Back off, then retry with the sameIdempotency-Keyfor the exact same request.503on the batch lane carriesRetry-After. Honor it.- Fix
400failures before retrying — the same invalid input is rejected again. - Log
request_idfrom the error body or thex-request-idheader in every support report.