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

Les erreurs **métier** émises par l'API utilisent cette 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` (lorsque renvoyé par l'application) | Vérifier l'authentification. |
| `403` | Refus de la passerelle, sans enveloppe JSON garantie | Vérifier la clé (absente, invalide, expirée ou révoquée), le domaine et le scope ; ne supposez pas que tout `403` porte `insufficient_scope`. |
| `404` | `unknown_session`, `unknown_configuration`, `unknown_compilation` | Vérifier l'identifiant et le domaine 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>
  Une clé invalide est refusée **avant** l'API métier : la passerelle peut répondre `403` sans `code`, `details` ni `request_id` dans le corps. Ne désérialisez l'enveloppe ci-dessus que si le corps la contient réellement.
</Note>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.