Refused requests
A refused request answers with its HTTP status and a JSON body with a code to switch on and a message to show. Some carry details: max (a limit, in bytes or a count) or retryAfterSeconds. A 429 also carries a Retry-After header.
{
"error": {
"code": "FILE_TOO_LARGE",
"message": "The file is larger than this key takes.",
"details": {
"max": 10485760
}
}
}| Code | Status | Meaning |
|---|---|---|
| INVALID_REQUEST | 400 | The body or the options are not valid; the message says what.Check the field names against the reference and the options against GET /tools. |
| UPLOAD_INCOMPLETE | 400 | A file has not finished uploading, or arrived empty.Wait for every PUT to answer 200 before starting the job. |
| WEBHOOK_URL | 400 | The webhook address is not a public HTTPS address. |
| API_KEY_MISSING | 401 | No key in the Authorization header.Send Authorization: Bearer uvp_live_… on every call. |
| API_KEY_INVALID | 401 | The key is unknown, revoked, or its account is closed. |
| API_CREDITS_SHORT | 402 | No API tasks left on the account, with a live key.Buy a pack on the keys page, or use a test key while developing. |
| API_ADDRESS | 403 | The key does not allow requests from this address. |
| API_SCOPE | 403 | A read-only key tried to make, start or cancel a job. |
| ACCOUNT_SUSPENDED | 403 | The account is suspended. |
| NOT_FOUND | 404 | No such job for this account. |
| ALREADY_STARTED | 409 | The job was started already. |
| FILE_TOO_LARGE | 413 | A file is larger than the tool or the key takes; details.max says the limit in bytes. |
| API_TEST_LIMIT | 429 | The 50 test jobs of the day are used.The count starts again at midnight UTC. |
| API_TOO_MANY_OPEN | 429 | 10 jobs are unfinished already.Wait for some to finish, or cancel the ones you no longer need. |
| TOO_MANY_REQUESTS | 429 | More than 120 requests in a minute with one key.Wait the seconds in the Retry-After header, then go on. |
| TOOL_UNAVAILABLE | 503 | The tool is not available for the moment. |
| MAINTENANCE | 503 | The servers are paused for maintenance. |
| API_OFF | 503 | The API is closed. |
Failed jobs
A job that could not be done ends in state failed with job.error set the same way, and the live task comes back. The webhook event is job.failed.
| Code | Meaning |
|---|---|
| NOT_A_PDF | The file is not a PDF. |
| CORRUPT_PDF | The PDF is too damaged to read.Try the repair tool first. |
| PASSWORD_REQUIRED | The PDF is locked with a password.Unlock it before sending; the API does not take passwords. |
| UNSUPPORTED_FILE | The file is of a kind the tool cannot read. |
| CONVERSION_FAILED | The converter could not produce a result, or the result failed its check. |
| TIMEOUT | The job took longer than the tool allows and was stopped. |
| INVALID_URL | The address is not public, or redirected somewhere that is not. |
| PAGE_UNREACHABLE | The web page did not load, or answered with an error. |
| NOTHING_TO_RECOGNIZE | OCR found no page without text to read. |
| NOT_AN_EPUB | The file is not an EPUB. |
| EPUB_PROTECTED | The book is protected and cannot be printed. |
| EPUB_TOO_LARGE | The book would print to more pages than the tool takes. |
| INPUT_MISSING | A file went missing before the job ran. |
| WORKER_ERROR | Something went wrong on our side; the task comes back.Try again; write to us if it repeats. |
| WORKER_LOST | The server running the job stopped answering; the task comes back. |