> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes, normalized error payloads, and practical retry guidance.

The API uses standard HTTP status codes and returns a normalized JSON error envelope for failures.

## Error envelope

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Request fields failed validation.",
    "retryable": false,
    "retry_after": null
  }
}
```

## HTTP status codes

| Status | Code                   | Meaning                                                                        | Retry? |
| ------ | ---------------------- | ------------------------------------------------------------------------------ | ------ |
| `400`  | `bad_request`          | Malformed JSON, invalid multipart, or mutually exclusive source inputs.        | No     |
| `401`  | `unauthorized`         | Missing or malformed bearer token.                                             | No     |
| `403`  | `forbidden`            | API access is disabled or the key does not belong to an approved organization. | No     |
| `404`  | `not_found`            | The requested job, source asset, or page does not exist for the caller.        | No     |
| `409`  | `idempotency_conflict` | The same `Idempotency-Key` was reused with a different payload.                | No     |
| `422`  | `validation_error`     | Request fields fail the workflow and capture-type validation matrix.           | No     |
| `429`  | `rate_limited`         | Per-key, per-org, or per-IP limit exceeded.                                    | Yes    |
| `500`  | `internal_error`       | Unexpected server-side failure.                                                | Yes    |

## Handling failures

* Treat authentication and validation failures as terminal until the request or access model is fixed.
* Retry `429` only after the advertised retry window.
* Retry retryable `5xx` failures with backoff.
* Keep the same idempotency key when retrying the same write request.