Skip to content
Coming soon. The hosted API is not live yet, and this page describes the planned service as of 16 November 2026. Get notified when it opens.

Errors

A failed call returns a JSON body with a stable code and a message that names the cause:

{ "error": { "code": "quality_unavailable", "message": "..." } }

Branch on code, not on message.

Status Meaning
400 The request is malformed, or an option is unknown or invalid. Unknown form fields and unknown options are refused.
401 The API key is missing or not valid.
404 The job does not exist.
413 The upload is larger than the operation accepts.
422 The document cannot be processed, for example because it is not a readable PDF.
500 The service failed while processing the call.
501 The operation or quality is not available on this deployment (quality_unavailable).
503 The service is temporarily unavailable. Retry shortly.
504 The call took longer than the operation allows synchronously. Run it as a job.

The gateway in front of the operations adds its own statuses: 402 when the credit balance is too low, 403 when the account is suspended or the call is outside the trial, 409 when an idempotency key was reused, 429 when a key sends too many calls, and 502 or 503 while a region recovers. They carry the same body.

Retry 429, 502, 503 and 504 with a short, growing delay. Do not retry 400, 401, 413 or 422 without changing the call.