Erreurs

Les erreurs métier émises par l’API utilisent cette forme :

{
  "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é.

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.

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

Guides API

Sessions

Configuration

Service