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`, `api_access_requires_purchase`	Use a key with the right scope, or buy credits to enable the API
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`

A job that fails after it started reports status: "failed" with an errorCode, and is not charged.