> ## 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.

# Erreurs

> Enveloppe d'erreur V1, principaux codes et stratégie de reprise.

Toutes les erreurs métier utilisent la même forme :

```json theme={null}
{
  "code": "state_version_conflict",
  "message": "La session a été modifiée depuis votre dernière lecture.",
  "request_id": "req_01J8Z",
  "details": {}
}
```

Conservez toujours `request_id` dans vos logs et communiquez-le au support.

| HTTP  | Codes fréquents                                                                                     | Action                                                                  |
| ----- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `401` | `unauthorized`                                                                                      | Vérifier ou remplacer la clé.                                           |
| `403` | `insufficient_scope`                                                                                | Utiliser une clé possédant le scope requis.                             |
| `404` | `unknown_session`, `unknown_configuration`, `unknown_compilation`                                   | Vérifier l'identifiant et le NBQ associé à la clé.                      |
| `409` | `state_version_conflict`, `idempotency_key_reused`, `compilation_in_progress`                       | Relire l'état ou utiliser une nouvelle clé d'idempotence selon le code. |
| `410` | `compiled_artifact_unavailable`                                                                     | Créer une nouvelle session sur une configuration disponible.            |
| `422` | `invalid_previous_turn`, `invalid_choice`, `constraint_no_match`, `configuration_validation_failed` | Corriger le corps ou la configuration.                                  |
| `429` | limite d'usage                                                                                      | Attendre selon les en-têtes reçus et appliquer un backoff avec jitter.  |
| `503` | `idempotency_contention`                                                                            | Réessayer brièvement avec la même intention et un backoff borné.        |

<Note>
  Un `degraded: true` dans une réponse réussie n'est pas une erreur HTTP. La décision reste utilisable ; consultez `degraded_reasons` pour votre observabilité.
</Note>