Errores y códigos de estado

El envelope de error

Toda respuesta distinta de 200 usa un único 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 siempre el request_id — ata la respuesta a la entrada de auditoría inmutable y a cualquier evento de lineage.

Bandas de códigos

Banda	Significado	HTTP típico
`E0xxx`	Schema / petición malformada	`400`
`E1xxx`	Resolución — petición válida, no se puede resolver (p. ej. métrica/faceta desconocida)	`422`
`E2xxx`	Política — deny del PDP o fail-closed	`403` / `503`
`E3xxx`	Internos del motor	`401` / `500`

Códigos vistos con frecuencia

Código	HTTP	Condición
`E0501`	`400`	Claves vacías — no se permite full-scan (`joint/resolve`, `traverse`)
`E0502` / `E0259`	`400`	Anchor/target no declarado o no alcanzable (`traverse`)
`E0511`	`400`	Fuera de gramática / no-SELECT / no reduce a un nodo IR (`query`)
`E0512`	`403`	Objeto no declarado / fuera del allowlist del tenant (`query`)
`E0513`	`400`	El body mezcla `osql` con `sql` o campos de MetricFlow (`query`)
`E0514`	`400`	`JOIN … ON` no es un equijoin de clave de entidad sellada — firewall R3 (`query`)
`E0515`	`403`	Clave de join cross-modal no en claro para el sujeto — fail-closed (`query`)
`E0521`	`503`	Op de proyección decoder (p. ej. `SUMMARIZE`) pero sin backend LLM (`query`)
`E0522`	`400`	La salida de una op generativa falló la validación (`query`)
`E0510`	`502`	Fallo de ejecución de Trino (`query`)
`E2001`	`403`/`503`	Deny del PDP (no revelador) / falta el snapshot del PDP (fail-closed)
`E2101` / `E2102`	`403`	Deny del PEP — fuera de scope / obligación bloqueante
`E3001`	`401`	Token inválido o caducado
`E0503`	`502`	Guard del control-plane — motor semántico inalcanzable (proxy del tier managed, no es un código del motor)

El modelo de error canónico y exhaustivo vive en la especificación §9.