Errors

Errors are JSON with a human-readable message and a stable machine code:

{ "error": "This credential is missing the 'documents:write' scope.", "code": "insufficient_scope" }

Status	Typical codes	What to do
400	`invalid_request`	Fix the request body or parameters
401	`unauthenticated`	Check the API key
402	`insufficient_credits`	Buy credits; the body says how many are needed
403	`insufficient_scope`	Use a key with the right scope
404	`not_found`	Check the ID; jobs expire after 7 days, receipts do not
413	`document_too_large`	Split the document (limit 1,000 pages)
429	`rate_limit_exceeded`	Wait for `Retry-After` seconds
5xx	`internal_error`	Retry with the same `Idempotency-Key`

Job failure codes

A job that fails after it started reports status: "failed", a human-readable error, and a stable errorCode. Failed jobs are not charged. Show the error text to the user: it says what to try. Retrying with the same Idempotency-Key returns the same failed job. To try again, send a new key.

`errorCode`	Meaning	Retry?
`unprocessable`	The converter could not read this file. It may be damaged, password-protected, or contain something the converter does not support; sometimes the converter gives no reason.	No. Retrying the same file is unlikely to help. Try an unprotected or re-exported copy, or a direct link to the file.
`timeout`	The document took too long to convert.	Not as is. Split it or try a simpler file.
`service_unavailable`	The converter is temporarily unavailable.	Yes, later.
`rate_limited`	The converter is busy.	Yes, after a short wait.
`stranded_running`	The job stopped making progress (for example, its worker went away). Not a problem with the file.	Yes, with a new `Idempotency-Key`.
`unknown`, `conversion_failed`	An unclassified failure.	Once. If it fails again, contact support with the job ID.
`document_too_large`	More than 1,000 pages. Refused before any credits were reserved.	No. Split the document.
`payload_too_large`	The file is over the 100 MB limit.	No. Use a smaller file.
`unsupported_media_type`	The file type is not supported.	No. See the supported formats.
`external_fetch_failed`	The `fileUrl` could not be downloaded, or the download took longer than 25 seconds.	After checking that the link is public and points at the file itself. For a slow link, upload the file instead (`create_upload` over MCP, or `POST /api/v1/uploads`).
`source_is_web_page`	The `fileUrl` served a web page, and the page did not declare a document to convert. A page that does declare one — an arXiv abstract page, for example — is converted from the document it points at, so this only reaches pages with nothing behind them. No credits are charged.	No. Link the file itself (a direct link, for example one ending in `.pdf`), or download the page’s document and upload it.
`unsafe_url`	The `fileUrl` points at a private or blocked address.	No. Use a public URL.
`invalid_file_source`, `invalid_cos_url`, `presign_failed`	The upload reference could not be used.	Create a new upload and start a new job.

Get started

Using the API

MCP

Job failure codes