Errori e codici di stato

L’envelope di errore

Ogni risposta diversa da 200 usa un unico 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 il request_id — lega la risposta alla voce di audit immutabile e a qualsiasi evento di lineage.

Bande di codici

Banda	Significato	HTTP tipico
`E0xxx`	Schema / richiesta malformata	`400`
`E1xxx`	Risoluzione — richiesta valida, non risolvibile (es. metrica/facet sconosciuto)	`422`
`E2xxx`	Policy — deny del PDP o fail-closed	`403` / `503`
`E3xxx`	Interni del motore	`401` / `500`

Codici visti di frequente

Codice	HTTP	Condizione
`E0501`	`400`	Chiavi vuote — full-scan non consentito (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Anchor/target non dichiarato o non raggiungibile (`traverse`)
`E0511`	`400`	Fuori grammatica / non-SELECT / non si abbassa a un nodo IR (`query`)
`E0512`	`403`	Oggetto non dichiarato / fuori dall’allowlist del tenant (`query`)
`E0513`	`400`	Il body mescola `osql` con campi `sql` o MetricFlow (`query`)
`E0514`	`400`	`JOIN … ON` non è un equijoin su chiave di entità sigillata — firewall R3 (`query`)
`E0515`	`403`	Chiave di join cross-modale non in chiaro per il soggetto — fail-closed (`query`)
`E0521`	`503`	Op di proiezione decoder (es. `SUMMARIZE`) ma nessun backend LLM (`query`)
`E0522`	`400`	L’output di un’op generativa non ha superato la validazione (`query`)
`E0510`	`502`	Fallimento di esecuzione di Trino (`query`)
`E2001`	`403`/`503`	Deny del PDP (non rivelatore) / manca lo snapshot del PDP (fail-closed)
`E2101` / `E2102`	`403`	Deny del PEP — fuori scope / obbligazione bloccante
`E3001`	`401`	Token non valido o scaduto
`E0503`	`502`	Guard del control-plane — motore semantico non raggiungibile (proxy del tier gestito, non è un codice del motore)

Il modello di errore canonico ed esaustivo vive nella specifica §9.