errors

Errors

Every error follows the same envelope and comes with an X-Request-Id header for support tickets.

{
  "error": {
    "code": "invalid_page_range",
    "message": "Page range \"7-10\" is invalid for a document with 4 page(s)",
    "details": { "range": "7-10", "maxPage": 4 }
  }
}

All error codes

HTTP	Code	When
400	invalid_parameters	Request was malformed — check `details` for specifics.
400	invalid_file	Uploaded PDF is corrupt or password-protected.
400	invalid_page_range	Range spec references pages outside the document.
400	unsupported_format	File MIME type is not accepted by this endpoint.
401	unauthenticated	Missing / malformed / revoked API key.
403	forbidden	Key lacks the required scope for this operation.
404	not_found	Resource (key, webhook, subscription) does not exist.
413	file_too_large	File exceeds your plan’s per-request limit.
415	unsupported_format	Alias of 400 for multipart MIME mismatch.
429	rate_limit_exceeded	Requests/min burst ceiling hit. Back off.
429	quota_exceeded	Monthly op quota exhausted. Upgrade or wait.
500	internal_error	Server bug. Include `x-request-id` when reporting.
500	ocr_failed	OCR engine error — try a lower DPI or different language.
500	encryption_failed	Protect driver was unavailable.

Retry policy

Our SDKs auto-retry 429 and 5xx responses with jittered exponential backoff, up to maxRetries (default 3). 4xx responses are never retried because the input is at fault.