> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/getting-started/errors.md).

# Error Handling

Understand API errors and failures

Every error response includes a message describing the problem. Image API errors come back as HTTP status codes; Video API errors add an `errorCode` field (for example `INVALID_INPUT`) and, for jobs that fail after acceptance, the same `errorCode` appears in the status response. Service-side failures are always refunded.

<details>

<summary>400 Bad Request / INVALID_INPUT</summary>

The request itself is malformed, so nothing was processed or charged. On the Image API this usually means an invalid `output_height` / `output_width`, a malformed `process_id`, or a bad estimate input. On the Video API the `errors[]` array lists the exact fields: common causes are an unsupported `videoEncoder` / `videoProfile` pair, an output resolution or bitrate over the encoder's cap, a `source.external` URL we can't reach, a missing required filter parameter (such as `rollingShutterCorrection` with `stab-1`), or trying to cancel a request that's already finished. Fix the request before retrying; the same request will fail the same way.

</details>

<details>

<summary>401 Unauthorized / UNAUTHORIZED</summary>

The `X-API-Key` header is missing, invalid, or belongs to a revoked key. Check that you're sending the header on every request (including status and download calls), that the key is copied exactly, and that it hasn't been deleted in your account. Not retryable until the key is fixed.

</details>

<details>

<summary>402 Payment Required / INSUFFICIENT_CREDITS</summary>

Your account doesn't have enough credits to reserve for this job. Image jobs reserve credits at submission; video jobs reserve them at `PATCH /video/{requestId}/accept`. Add credits or enable auto top-up, then resubmit. Don't put `402` in a retry loop; it will fail until the balance changes. If a video job fails with `INSUFFICIENT_CREDITS` after acceptance, the credits ran out between estimate and reservation; add credits and resubmit.

</details>

<details>

<summary>403 Forbidden / FORBIDDEN</summary>

There are two different 403s, and the response body tells them apart.

**A Cloudflare error page (error 1010, "browser\_signature\_banned").** The request was blocked by our web application firewall before reaching the API, usually because the client's fingerprint matches patterns we block. Fix it in this order:

1. Set a descriptive `User-Agent` header that identifies your application (for example `MyApp/1.0 (contact@example.com)`). Default library agents like Python's `urllib` or `python-requests` are frequently blocked.
2. Check the path. The Image API base is `https://api.topazlabs.com/image/v1/` and the Video API is `https://api.topazlabs.com/video/`; a request to a non-existent path (e.g. `/image/v1/process`) can also trigger a block.
3. If it persists, send support the Cloudflare **Ray ID** from the response, your egress IP, and the User-Agent you're sending. We can add an exception for identified traffic.

**A JSON error from the API.** Your key is valid but doesn't have access to this endpoint, model, or request. On the Video API this also happens when the `requestId` belongs to a different account. Check which key you're using and whether the model requires an enterprise plan.

</details>

<details>

<summary>404 Not Found</summary>

No job exists with that `process_id` or `requestId`. Check that you're using the ID returned from the submission and that it belongs to the same account as the key. Image status history only covers the last 7 days, so older jobs also return 404. On the Video API a 404 carries `errorCode: INVALID_INPUT`.

</details>

<details>

<summary>409 Conflict (Image API)</summary>

You called an endpoint at the wrong point in the job's lifecycle: most often `GET /download/{process_id}` before the job reached `Completed`, or `cancel` on a job that already finished. For downloads, poll `GET /status/{process_id}` until it reports `Completed`, then retry. For cancels, the job can't be cancelled and the full charge applies.

</details>

<details>

<summary>412 Precondition Failed (Image API)</summary>

The account has no active API subscription. API access requires an API plan; desktop, web, or Pro subscriptions don't include it. Subscribe or reactivate a lapsed plan, then retry.

</details>

<details>

<summary>413 Request Entity Too Large</summary>

Image: the uploaded file exceeds the upload size limit. Downscale or compress the input, or upload once and reuse the `source_id` for subsequent jobs. Video: the JSON request body exceeds 3,000 bytes and the response has no body at all. The usual cause is long presigned URLs in `source.external` or `destination.external`; shorten them (fewer query parameters, shorter expiry tokens) or reduce the number of filters.

</details>

<details>

<summary>415 Unsupported Media Type (Image API)</summary>

The file couldn't be decoded as JPEG, PNG, or TIFF. Check that the file is actually one of those formats (not HEIC, WebP, or a renamed file), that it isn't truncated, and that you're sending it as `multipart/form-data` in the `image` field rather than as a raw body or base64 string.

</details>

<details>

<summary>422 Unprocessable Entity (Image API)</summary>

The image decoded but has invalid dimensions, typically a zero width or height. This usually indicates a corrupt file or a failed export from your pipeline. Re-export the image and resubmit.

</details>

<details>

<summary>425 Too Early (Image API)</summary>

A credit purchase or top-up is still settling, so credits can't be reserved yet. Wait a few seconds and retry; this one is safe to retry with backoff.

</details>

<details>

<summary>429 Too Many Requests</summary>

You've exceeded the request rate limit. Back off and retry with exponential backoff and jitter, honoring the `Retry-After` header when present. Spread submissions out rather than bursting them, and prefer webhooks over tight polling loops. If you consistently need more throughput, contact us about an enterprise plan.

</details>

<details>

<summary>500 Internal Server Error / SERVER_ERROR</summary>

Something failed on our side. Retry with exponential backoff; most 500s are transient. If a video job fails with `SERVER_ERROR` after acceptance, the credits are refunded automatically. If the error persists for more than a few minutes, contact support with the timestamp, endpoint, and `process_id` / `requestId`.

</details>

<details>

<summary>503 Service Unavailable / SERVER_MAINTENANCE (Video API)</summary>

Cloud video rendering is temporarily disabled for maintenance. `GET /video/status` reports `isAvailable` and a message. Check it before retrying rather than polling the submit endpoint. Jobs that were in flight when maintenance started are refunded.

</details>

<details>

<summary>My video job failed with CREDIT_DIFFERENCE</summary>

After analyzing the uploaded source, the re-estimated cost differed significantly from the estimate we gave you at `POST /video/`, so the job was stopped and fully refunded rather than charging you an amount you didn't agree to. This almost always means the `source` metadata you sent (duration, frame count, frame rate, resolution) didn't match the file. Read the real values from the file (for example with `ffprobe`) and resubmit.

</details>

<details>

<summary>My video job failed with TIMEOUT_UPLOAD_SOURCE, TIMEOUT_QUEUE, or TIMEOUT_PROCESSING</summary>

Three different timeouts, all refunded.

* **`TIMEOUT_UPLOAD_SOURCE`.** You accepted the request but didn't finish uploading the source in time. Resubmit and upload promptly after accepting; for large files use the multi-part upload URLs.
* **`TIMEOUT_QUEUE`.** The request waited in the queue past the limit, usually during a load spike. Resubmit.
* **`TIMEOUT_PROCESSING`.** Processing exceeded the model's time limit. Resubmit, or split long sources into shorter segments.

</details>

<details>

<summary>My video job failed with PROCESSING_FAILURE or HARDWARE_FAILURE</summary>

`PROCESSING_FAILURE` means the model couldn't process this particular source; `HARDWARE_FAILURE` means the GPU or infrastructure failed mid-job. Both are refunded. Retry once. If `PROCESSING_FAILURE` recurs on the same file, the source is likely the cause (unusual codec, variable frame rate, corrupt frames); try re-encoding it to a standard H.264 MP4 and, if that doesn't help, send support the `requestId`.

</details>

<details>

<summary>My video job failed with INVALID_INPUT after it was accepted</summary>

The source file couldn't be processed as described: it may be corrupt, in a different container than `source.container` claims, or its metadata may not match what you sent. Verify the file plays locally, correct the `source` block, and resubmit. Nothing is charged.

</details>

<details>

<summary>My video job failed with UNKNOWN, FORBIDDEN, or UNAUTHORIZED</summary>

`UNKNOWN` is an unclassified failure; it's refunded, and support can look up the cause from the `requestId`. `FORBIDDEN` / `UNAUTHORIZED` on an already-accepted job mean authorization changed mid-request, for example the key was deleted or the account's plan lapsed. Check your key and subscription, then resubmit.

</details>

<details>

<summary>Will I be refunded for a failed job?</summary>

Yes, when the failure is on our side: timeouts, processing or hardware failures, server errors, maintenance, and `CREDIT_DIFFERENCE` are all refunded in full, usually within 24 hours. Requests rejected synchronously with a `4xx` are never charged. If you cancel a job in progress you're charged for the work done (1.1 × progress %) and refunded the rest; video requests can preview the split with `GET /video/{requestId}/cancel-estimate`.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.topazlabs.com/getting-started/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
