Fehler & Statuscodes

Das Error-Envelope

Jede Antwort ungleich 200 verwendet ein einziges 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."
  }
}

Logge immer die request_id — sie verknüpft die Antwort mit dem unveränderlichen Audit-Eintrag und allen Lineage-Events.

Code-Bänder

Band	Bedeutung	Typisches HTTP
`E0xxx`	Schema / fehlerhafte Anfrage	`400`
`E1xxx`	Resolve — gültige Anfrage, nicht auflösbar (z. B. Metrik/Facette unbekannt)	`422`
`E2xxx`	Policy — PDP-Deny oder fail-closed	`403` / `503`
`E3xxx`	Engine-Interna	`401` / `500`

Häufig gesehene Codes

Code	HTTP	Bedingung
`E0501`	`400`	Leere Schlüssel — kein Full-Scan erlaubt (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Anchor/Target nicht deklariert oder nicht erreichbar (`traverse`)
`E0511`	`400`	Außerhalb der Grammatik / Nicht-SELECT / senkt nicht zu einem IR-Knoten ab (`query`)
`E0512`	`403`	Nicht-deklariertes Objekt / außerhalb der Allowlist des Tenants (`query`)
`E0513`	`400`	Body mischt `osql` mit `sql`- oder MetricFlow-Feldern (`query`)
`E0514`	`400`	`JOIN … ON` ist kein Equijoin auf versiegeltem Entity-Schlüssel — R3-Firewall (`query`)
`E0515`	`403`	Cross-modaler Join-Schlüssel nicht Klartext für das Subject — fail-closed (`query`)
`E0521`	`503`	Decoder-Projektionsoperator (z. B. `SUMMARIZE`), aber kein LLM-Backend (`query`)
`E0522`	`400`	Output eines generativen Ops hat die Validierung nicht bestanden (`query`)
`E0510`	`502`	Trino-Ausführungsfehler (`query`)
`E2001`	`403`/`503`	PDP-Deny (nicht-enthüllend) / PDP-Snapshot fehlt (fail-closed)
`E2101` / `E2102`	`403`	PEP-Deny — außerhalb des Scope / blockierende Obligation
`E3001`	`401`	Ungültiges oder abgelaufenes Token
`E0503`	`502`	Control-Plane-Guard — semantische Engine nicht erreichbar (Proxy der Managed-Stufe, kein Engine-Code)

Das kanonische, vollständige Fehlermodell lebt in der Spezifikation §9.