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.
Statuses
Section titled “Statuses”| 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.
Retrying
Section titled “Retrying”Retry 429, 502, 503 and 504 with a short, growing delay. Do not retry 400, 401, 413 or 422 without changing the call.