Extract errors

Extract's error envelope — the one place in the API that returns a code.

dev · https://api.dev.oprag.ai

Extract returns a machine-readable code alongside the message. The rest of the API does not, so do not generalise from this page.

JSON

{
  "error": "Schema not found",
  "code": "NOT_FOUND"
}

Status	`code`	Typically
`400`	`VALIDATION_ERROR`	Bad body, unsupported format, or an oversized prompt.
`401`	`UNAUTHORIZED`	Missing or invalid integration key.
`404`	`NOT_FOUND`	Unknown or malformed job or schema id.
`409`	`CONFLICT`	A built-in schema cannot be changed, a schema already exists, or a job is past the point of confirming.
`429`	`TOO_MANY_REQUESTS`	Too many schema writes, or the active custom-schema limit is reached.
`503`	`SERVICE_UNAVAILABLE`	Extract is not enabled in this environment.

Job failure codes

A job can be accepted with 202 and still fail minutes later. When a poll returns status: "failed", error.code is one of these — a different axis from the HTTP codes above, which say why a *request* was refused.

JSON

{
  "jobId": "ext_a1b2c3d4e5f6789012345678abcdef01",
  "status": "failed",
  "error": {
    "code": "password_protected",
    "message": "Document is password protected"
  }
}

`error.code`	Means	What to do
`unsupported_format`	The file is not a format Extract can read, or its content contradicts its declared MIME type.	Convert it to a supported format and submit a new job. Retrying will not help.
`password_protected`	The document is encrypted and cannot be opened without a password.	Remove the password and re-upload. Extract never prompts for one.
`corrupt_file`	The file opened but could not be read — no pages, or a truncated upload.	Check the upload completed, then re-upload. A short read at upload time shows up here rather than at confirm.
`timeout`	Extraction ran past its time budget, usually on a very large or very dense document.	Retry once. If it recurs, split the document and submit the parts separately. Provider throttling is classified here too, so a retry after a pause often succeeds.
`extraction_failed`	The model could not produce a result for this document and schema.	Retry once. If it recurs, check the schema fits the document — `"auto"` classification often does better than a forced `schemaId`.

Confirm-time failures

Confirm re-checks the uploaded object, so most surprises land there rather than at upload: a missing or empty object, one over the size limit, or a file whose magic bytes contradict its MIME type. A 409 at confirm means the job is already processing or finished — a queued job confirms again idempotently.

The main API's envelope has no code — see errors.

Ready to ship?

Get started free