A successful HTTP response does not mean that conversion succeeded. A task query can return 200 with status: "failed". Check HTTP status first, then task status and error.code.
API errors
API errors usually return the following JSON structure. Authentication failures and file upload or download errors may return other formats.
{ "error": { "code": "SOURCE_FILE_MISSING", "message": "source file must be uploaded before launch" }}| HTTP / code | What to do |
|---|---|
400 INVALID_REQUEST | Check field names, language codes, input/output combinations and query parameters. Correct the request before retrying |
401 | Check the API key and environment. Replace invalid credentials |
404 | Check the account and task ID. The task may have expired; result download also returns 404 before success |
409 SOURCE_FILE_MISSING | Upload the source, then launch the same task |
409 TRANSFORM_CONCURRENCY_LIMIT | Wait for a running slot, then retry the same task before expiry |
409 TRANSFORM_ALREADY_LAUNCHED | Use the original parameters; create a new task only if you deliberately want a different conversion |
429, 502, 503, 504 | For reads, use bounded backoff and honor Retry-After when present. For writes, first establish whether the operation was accepted |
Use error.code to identify errors in your application; error.message is for human readers. Log unknown codes for troubleshooting.
Rate-limit headers may be absent, so your application still needs to handle 429 responses.
Processing failures
When status is failed, read the error details with GET /transforms/{uuid}. The finished list includes the same error.
error.code | Recovery |
|---|---|
INVALID_SOURCE_FILE | Repair or re-export the PDF/EPUB, then create a new task and upload the corrected file |
BALANCE_EXHAUSTED | Check and replenish account credit before submitting new work |
INVALID_ARTIFACT | Keep the task ID and contact support; repeatedly uploading the same source is not a reliable fix |
INTERNAL_ERROR or an unknown code | Keep the task ID, time and error code for support; do not run an automatic loop creating new tasks |
Calling launch again will not restart a failed task. To retry, create a new task, which may incur further processing charges. Previews generated before the failure contain only partial content.
Network and storage failures
If the create response is lost, check the waiting list before creating another task. After an interrupted upload, request upload URLs again to see whether the source exists. After an ambiguous launch, GET the task or retry with identical parameters.
If an upload or download link expires, request a new one from the API. Upload with PUT and the returned headers. Download with get_url, or use head_url for a HEAD request to inspect file information. None of these file requests require an API key. See lifecycle and recovery for recovery steps.
For support, send the task uuid, approximate request time, HTTP status and error.code to support@oomol.com. Do not include API keys or signed storage URLs.