> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-dev.ltx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-dev.ltx.io/_mcp/server.

# Error Handling

> Learn how LTX communicates errors and how to handle them gracefully. Includes error codes, response examples, and best practices.

## Error response format

Errors use this structure:

```json
{
  "type": "error",
  "error": {
    "type": "error_type",
    "message": "Human-readable error message"
  }
}
```

The same `{ type, message }` shape surfaces in three places:

* **V1 (sync):** in the response body when the request fails.
* **V2 (async), submit:** in the response body when the request fails.
* **V2 (async), job failure:** in the `error` field of a status payload with `status: "failed"`. See [Async Jobs](/async-jobs#error-handling) for the full shape.

## Error types

| Status | Error type                  | Retry? | What it means                                                             |
| ------ | --------------------------- | ------ | ------------------------------------------------------------------------- |
| 400    | `invalid_request_error`     | No     | Invalid request parameters.                                               |
| 401    | `authentication_error`      | No     | API key missing or invalid.                                               |
| 402    | `insufficient_funds_error`  | No     | Not enough credits. See [Pricing](/pricing).                              |
| 403    | `permission_error`          | No     | This endpoint is not available for your account.                          |
| 404    | `not_found_error`           | No     | Job doesn't exist or has expired.                                         |
| 422    | `content_filtered_error`    | No     | Content rejected by safety filters.                                       |
| 429    | `concurrency_limit_error`   | Yes    | Too many concurrent requests (sync API). See [Rate Limits](/rate-limits). |
| 429    | `rate_limit_error`          | Yes    | Queue limit exceeded (async API). See [Rate Limits](/rate-limits).        |
| 500    | `api_error`                 | Yes    | Unexpected server error.                                                  |
| 503    | `service_unavailable_error` | Yes    | Service temporarily unavailable.                                          |
| 529    | `overloaded_error`          | Yes    | API temporarily overloaded. Retry after a short delay.                    |

## Retry guidance

For retryable errors, use exponential backoff with jitter — a random delay of up to 50% of your backoff interval prevents thundering-herd retries. On `429`, honor the `Retry-After` header if present.