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

# Errors

> Understand the uniform V1 error envelope and safe retry behavior.

V1 errors use the same shape across runtime and configuration routes:

```json theme={null}
{
  "code": "state_version_conflict",
  "message": "The session changed since it was last read.",
  "request_id": "req_01J8...",
  "details": {
    "current_state_version": 4
  }
}
```

| Field        | Purpose                                                     |
| ------------ | ----------------------------------------------------------- |
| `code`       | Stable machine-readable identifier. Branch on this value.   |
| `message`    | Human-readable summary, not a stable programmatic contract. |
| `request_id` | Correlation identifier to include in support requests.      |
| `details`    | Optional structured context specific to the error.          |

## Common status codes

| Status | Common codes                                                                                        | Recommended action                                                      |
| ------ | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `401`  | `unauthorized`                                                                                      | Check or replace the key.                                               |
| `403`  | `insufficient_scope`                                                                                | Use a key with the required scope.                                      |
| `404`  | `unknown_session`, `unknown_configuration`, `unknown_compilation`                                   | Check the identifier and NBQ attached to the key.                       |
| `409`  | `state_version_conflict`, `idempotency_key_reused`, `compilation_in_progress`                       | Read current state or use a new idempotency key, depending on the code. |
| `410`  | `compiled_artifact_unavailable`                                                                     | Create a new session on an available configuration.                     |
| `422`  | `invalid_previous_turn`, `invalid_choice`, `constraint_no_match`, `configuration_validation_failed` | Correct the payload or configuration.                                   |
| `429`  | usage limit                                                                                         | Wait as directed by response headers and use backoff with jitter.       |
| `503`  | `idempotency_contention`                                                                            | Retry briefly with the same intent and bounded backoff.                 |

<Tip>
  Log the `request_id`, endpoint, status, and `code`, but never the `Authorization` header or unnecessary visitor text.
</Tip>

<Note>
  `degraded: true` in a successful response is not an HTTP error. The decision remains usable; inspect `degraded_reasons` for observability.
</Note>