Cómo leer los errores

Los errores vuelven como application/problem+json al estilo de RFC 7807. type es una URI identificadora estable, y cada una tiene su página de explicación en https://docs.d2b.dev/errors/<slug>.

{
  "type": "https://docs.d2b.dev/errors/validation",
  "title": "Transform validation failed",
  "detail": "Avoid hard-coding source names in the template …",
  "status": 400,
  "trace_id": "8f3c…",
  "suggested_fix": "Use {{ arg }} placeholders and bind via `args`. See /api/v1/workbooks/{cid}/artifacts to discover names.",
  "alternative_tools": ["get_lineage"]
}

suggested_fix está redactado como una frase que un LLM puede leer tal cual para decidir su siguiente acción — el patrón recomendado es pasar el mensaje de la excepción completo al loop del agente. El SDK lanza excepciones con suggested_fix incluido, y la CLI imprime la misma frase por stderr.

type	status típico	Significado
validation	400 / 422	La entrada no cumple el contrato (SQL que falla, nombres no permitidos, referencias hardcodeadas en la plantilla, etc.)
propagation-failed	400	La transformación se guardó y materializó; después falló la reconstrucción de una transformación posterior
unauthorized	401	PAT ausente, inválido o revocado
forbidden	403	Scope insuficiente, rechazo por política (mask / deny), fuera del scope del workbook
unknown-workbook	404	El workbook no existe o no es visible
unknown-artifact	404	La tabla / el artifact no existe, o es un tipo no expuesto en /api/v1
conflict	409	Bloqueo optimista (expected_version desactualizado), workbook en procesamiento, nombre duplicado
rate-limited	429	Límite de tasa. Obedece Retry-After
internal	5xx	Falla del lado del servidor. Contacta soporte adjuntando el trace_id

5xx y trace_id

Las respuestas 5xx usan el mismo problem+json. El trace_id (también en la cabecera X-D2B-Trace-Id) se corresponde 1:1 con el stack trace del servidor — inclúyelo al reportar. Los jobs de ingest asíncrono fallidos también llevan trace_id y la fase fallida (phase).

Para superficies donde el vocabulario REST (GET /api/...) no encaja, los errores aplicables incluyen además suggested_fix_cli (vocabulario d2b ...). La CLI muestra esa variante automáticamente.