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.

Uploads are processed asynchronously. The upload request itself fails for problems with the request: authentication, invalid input, size, an unsupported file type (415), paid API processing being off with the free allowance used up (402), an idempotency conflict or full capacity. Problems found while a file is processed, such as too many pages or an unreadable PDF, are reported as the job's error with the same codes; the status column then indicates the kind of failure rather than an HTTP response you receive.

Error envelope

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is not valid."
  }
}

Error codes

Code	Status	Meaning
billing_verification_required	402	The first 10 documents are free without verification. The workspace owner verifies once with Smart-ID, ID-card or Mobile-ID in Billing; paused documents then resume automatically.
queue_full	429	Upload or processing queue capacity is full. Retry after 30 seconds with the same Idempotency-Key.
request_too_large	413	Upload requests must not exceed 100 MB in total. Split the batch.
idempotency_conflict	409	This Idempotency-Key was already used for different files or options.
billing_details_required	402	Add invoice details in Billing to process more than 10 documents this month. Paused documents resume automatically once they are saved.
quota_exceeded	402	This document was stopped by an earlier billing limit. Check Billing, then retry.
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.
input_too_large	413	The document has too many or too large pages to process in one request. Split it into smaller files.
job_cancelled	409	The job was cancelled before it produced a document.
job_not_cancellable	409	The job already produced a document. Delete the document instead.
job_not_retryable	409	Only failed jobs whose original file is still retained can be retried. Upload the file again otherwise.
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.
file_not_available	404	The original file is not stored for this document. Documents processed before original files were kept have only their result.
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.

Capacity limits are reported as 429 queue_full, including the limit of 2 uploads in progress per workspace. The API does not rate-limit requests per key; rate_limited only appears on a job when an upstream processing limit persists after automatic retries. Retry after the response's Retry-After with the same Idempotency-Key rather than immediately. Reusing a key with different files or options returns 409 (idempotency_conflict).