Guide

Errors

Failures always use the same envelope as success, with success: false and an error object. Branch on error.code rather than on the message, and treat 5xx codes as retryable with exponential backoff.

Error envelope

{
  "success": false,
  "error": {
    "code": "unsupported_media_type",
    "message": "Upload PDF, PNG, JPEG, WEBP, TIFF, or BMP."
  }
}

Error codes

Code	Status	Meaning
billing_details_required	402	Complete invoice details in My profile to process more than 10 documents per month. Your tier then adjusts automatically with usage.
quota_exceeded	402	This workspace has reached its monthly document limit. Upgrade the plan or wait until next month.
api_billing_required	402	The free API allowance has been used. The workspace owner can enable paid API processing in Billing.
api_custom_plan_required	402	Contact us to agree a custom price before processing more than 250,000 paid API documents this month.
missing_api_key	401	Provide an API key via X-API-Key or Authorization: Bearer.
invalid_api_key	401	The provided API key is not valid.
invalid_request	400	The request is invalid. Check the documented parameters and upload format.
unsupported_media_type	415	Upload PDF, PNG, JPEG, WEBP, TIFF, or BMP.
file_too_large	413	Files must not exceed 25 MB each.
too_many_pages	422	Documents must not exceed 10 pages. Split the document before uploading.
pdf_unreadable	422	The PDF could not be read. Upload a valid PDF or page image.
pdf_password_required	422	Remove the PDF password before uploading.
not_found	404	The requested resource was not found.
rate_limited	429	Too many requests. Wait before retrying.
service_unavailable	503	Document processing is temporarily unavailable. Please retry later.
processing_failed	502	The document could not be processed. Retry, or contact support if the problem continues.
internal_error	500	An unexpected error occurred. Please retry or contact support.

Rate limits are reported as 429 through the rate_limited code. Retry after a short delay rather than immediately.