Błędy i kody statusu

Envelope błędu

Każda odpowiedź różna od 200 używa jednego envelope’u:

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

Zawsze loguj request_id — wiąże odpowiedź z niezmiennym wpisem audytowym i wszelkimi zdarzeniami lineage.

Pasma kodów

Pasmo	Znaczenie	Typowy HTTP
`E0xxx`	Schema / zniekształcone żądanie	`400`
`E1xxx`	Rozwiązywanie — poprawne żądanie, nie da się rozwiązać (np. nieznana metryka/faseta)	`422`
`E2xxx`	Polityka — deny PDP lub fail-closed	`403` / `503`
`E3xxx`	Wnętrze silnika	`401` / `500`

Często spotykane kody

Kod	HTTP	Warunek
`E0501`	`400`	Puste klucze — full-scan niedozwolony (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Anchor/target niezadeklarowany lub nieosiągalny (`traverse`)
`E0511`	`400`	Poza gramatyką / nie-SELECT / nie obniża się do węzła IR (`query`)
`E0512`	`403`	Obiekt niezadeklarowany / poza allowlistą tenanta (`query`)
`E0513`	`400`	Ciało miesza `osql` z polami `sql` lub MetricFlow (`query`)
`E0514`	`400`	`JOIN … ON` nie jest equijoinem na zapieczętowanym kluczu encji — firewall R3 (`query`)
`E0515`	`403`	Klucz joina cross-modalnego niejawny dla podmiotu — fail-closed (`query`)
`E0521`	`503`	Operacja projekcji decoder (np. `SUMMARIZE`), ale brak backendu LLM (`query`)
`E0522`	`400`	Wyjście operacji generatywnej nie przeszło walidacji (`query`)
`E0510`	`502`	Niepowodzenie wykonania Trino (`query`)
`E2001`	`403`/`503`	Deny PDP (nieujawniający) / brak snapshotu PDP (fail-closed)
`E2101` / `E2102`	`403`	Deny PEP — poza scope’em / obowiązek blokujący
`E3001`	`401`	Token nieprawidłowy lub wygasły
`E0503`	`502`	Guard control-plane — silnik semantyczny nieosiągalny (proxy tieru zarządzanego, nie jest to kod silnika)

Kanoniczny, wyczerpujący model błędów żyje w specyfikacji §9.