Reference

Errors

Every error type the API returns, for refused requests and for documents that fail.

There are two kinds. A request that is refused gets a 4xx status and an error body. A document that was accepted but then failed answers 200 with status: "failed" and an error on the document. Either way, branch on error.type, which never changes; the message is for people.

{
  "error": {
    "type": "invalid_request",
    "message": "Invalid options.",
    "details": { "markdown": ["requires analysis \"layout\""] }
  }
}

When a request is refused

401 unauthorized · missing, revoked or expired key
402 insufficient_credits · not enough credit for this work
402 quota_exceeded · the trial's monthly request cap is used up
403 not_entitled · your plan does not include this
404 not_found · no such document or query for this key
409 document_not_ready · the document has not finished yet
409 conflict · a question on it is still running; try again
410 document_expired · retention ran out and the result was deleted
413 payload_too_large · the file is over your plan's size limit
415 unsupported_media_type · not a file type we read
422 invalid_request · the body or options are wrong; see details
422 document_too_large · too many pages for your plan, or too long for the model
429 rate_limited · too many requests this second; see Retry-After

When a document fails

error.stage says which step it stopped at. You pay only for work done before the failure.

`fetch_failed`	We could not download the link (a server error or timeout).
`unsupported_media_type`	The file, or what the link returned, is not something we read. A link that answers 4xx lands here too.
`payload_too_large`	The downloaded file is over your plan's size limit.
`document_too_large`	Too many pages for your plan, or too much text for the chosen model.
`insufficient_credits`	There was not enough credit to cover the job once its real size was known.
`analysis_failed`	The OCR could not read the file, for example because it is damaged.
`schema_mismatch`	The model could not fill your schema correctly, even after a second try. Loosen the schema or add `instructions`.
`embedding_failed`	The vectors could not be made.
`processing_failed`	Anything else. The message says what happened.