Errors i codis d'estat

L’envelope d’error

Cada resposta diferent de 200 usa un sol 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."
  }
}

Registra sempre el request_id — lliga la resposta a l’entrada d’auditoria immutable i a qualsevol esdeveniment de lineage.

Bandes de codis

Banda	Significat	HTTP típic
`E0xxx`	Schema / petició malformada	`400`
`E1xxx`	Resolve — petició vàlida, no es pot resoldre (p. ex. mètrica/faceta desconeguda)	`422`
`E2xxx`	Política — deny de la PDP o fail-closed	`403` / `503`
`E3xxx`	Interns del motor	`401` / `500`

Codis vistos habitualment

Codi	HTTP	Condició
`E0501`	`400`	Claus buides — sense full-scan permès (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Àncora/target no declarats o no assolibles (`traverse`)
`E0511`	`400`	Fora de gramàtica / no-SELECT / no baixa a un node d’IR (`query`)
`E0512`	`403`	Objecte no declarat / fora de l’allowlist del tenant (`query`)
`E0513`	`400`	El body barreja `osql` amb `sql` o camps MetricFlow (`query`)
`E0514`	`400`	`JOIN … ON` no és un equijoin de clau d’entitat segellada — firewall R3 (`query`)
`E0515`	`403`	Clau de join cross-modal no en clar per al subjecte — fail-closed (`query`)
`E0521`	`503`	Op de projecció decoder (p. ex. `SUMMARIZE`) però sense backend LLM (`query`)
`E0522`	`400`	La sortida d’una op generativa ha fallat la validació (`query`)
`E0510`	`502`	Fallada d’execució de Trino (`query`)
`E2001`	`403`/`503`	Deny de la PDP (no revelador) / falta l’snapshot de la PDP (fail-closed)
`E2101` / `E2102`	`403`	Deny del PEP — fora de scope / obligació bloquejant
`E3001`	`401`	Token invàlid o caducat
`E0503`	`502`	Guarda del control-plane — motor semàntic no assolible (proxy del tier gestionat, no un codi del motor)

El model d’error canònic i exhaustiu viu a l’especificació §9.