Error codes
Errors are JSON with a detail (a text, or a list for 422). This is the complete list of statuses you can meet, with the endpoints where they appear in the API reference. The guide to errors explains how to handle them in code.
| Status | Meaning | Typical message | What to do |
|---|---|---|---|
| 400 | A parameter is not valid | Invalid format 'txt'. Allowed: html, json, markdown · Invalid JSON schema provided… · Webhook URL must be an absolute http(s) URL |
Fix the request; do not retry unchanged |
| 401 | The API key is missing, wrong or revoked | Not authenticated (no key) · Could not validate credentials or token expired (wrong or revoked key) |
Check the Authorization: Bearer header and that the key is active |
| 402 | The page quota is used up (the month and the welcome pages), or the document needs more pages than remain | Page quota exceeded (50/50 monthly pages used, 0 welcome pages left)… |
Wait for the renewal on the first of the month, or contact support |
| 403 | The job belongs to another user | Access forbidden: this job belongs to another user |
Use the key of the account that created the job |
| 404 | The job or the key does not exist | Job with ID '…' not found · API Key not found or does not belong to you |
Check the identifier |
| 413 | The file is over 50 MB, or the batch over 100 files or 200 MB | a message with the limit | Split the upload |
| 422 | A required field is missing or malformed | a list with loc, msg and type |
Check the field names and the multipart/form-data encoding |
| 429 | Too many conversion requests per minute (/v1/convert, /v1/convert/batch) |
Rate limit exceeded… with Retry-After |
Wait for Retry-After seconds, then retry |
| 500 | The document could not be processed | Document parsing error: … |
Check the file; see Errors and troubleshooting |
| 503 | The OCR provider is not answering while an image is being read (Retry-After: 60); no pages are charged. On /health: the database does not answer |
a short unavailability message | Wait and retry |
Errors that concern one file of a batch are not HTTP errors: they appear in that file's entry of results with status: "error". An asynchronous job that fails has status: "failed" and the reason in error_message.