# Errors and retries

[HTML](https://pdfcraft.ai/docs/api/error-handling/)
[Site index](https://pdfcraft.ai/llms.txt)

Error codes and how to handle them.


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.

```json
{
  "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](https://pdfcraft.ai/docs/api/lifecycle/) for recovery steps.

For support, send the task `uuid`, approximate request time, HTTP status and `error.code` to [support@oomol.com](mailto:support@oomol.com). Do not include API keys or signed storage URLs.