Erreurs et codes de statut

L’envelope d’erreur

Toute réponse différente de 200 utilise un unique envelope :

{
  "request_id": "01HV...",
  "error": {
    "code": "E2001",
    "severity": "error",
    "message": "Access denied for this operation",
    "object": { "kind": "Metric", "name": "arr" },
    "hint": "Contact policy author. Use request_id for support."
  }
}

Loggez toujours le request_id — il relie la réponse à l’entrée d’audit immuable et à tout événement de lineage.

Bandes de codes

Bande	Signification	HTTP typique
`E0xxx`	Schema / requête malformée	`400`
`E1xxx`	Résolution — requête valide, impossible à résoudre (p. ex. métrique/facette inconnue)	`422`
`E2xxx`	Politique — deny du PDP ou fail-closed	`403` / `503`
`E3xxx`	Internes du moteur	`401` / `500`

Codes vus fréquemment

Code	HTTP	Condition
`E0501`	`400`	Clés vides — full-scan interdit (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Anchor/target non déclaré ou non atteignable (`traverse`)
`E0511`	`400`	Hors grammaire / non-SELECT / ne s’abaisse pas en un nœud IR (`query`)
`E0512`	`403`	Objet non déclaré / hors de l’allowlist du tenant (`query`)
`E0513`	`400`	Le body mélange `osql` avec `sql` ou des champs MetricFlow (`query`)
`E0514`	`400`	Le `JOIN … ON` n’est pas un equijoin sur clé d’entité scellée — firewall R3 (`query`)
`E0515`	`403`	Clé de join cross-modal non en clair pour le sujet — fail-closed (`query`)
`E0521`	`503`	Op de projection decoder (p. ex. `SUMMARIZE`) mais pas de backend LLM (`query`)
`E0522`	`400`	La sortie d’un op génératif a échoué à la validation (`query`)
`E0510`	`502`	Échec d’exécution de Trino (`query`)
`E2001`	`403`/`503`	Deny du PDP (non révélateur) / snapshot du PDP manquant (fail-closed)
`E2101` / `E2102`	`403`	Deny du PEP — hors scope / obligation bloquante
`E3001`	`401`	Token invalide ou expiré
`E0503`	`502`	Guard du control-plane — moteur sémantique inatteignable (proxy du tier géré, pas un code du moteur)

Le modèle d’erreur canonique et exhaustif vit dans la spécification §9.