Como ler os erros

Os erros retornam como application/problem+json, no estilo da RFC 7807. O type é uma URI identificadora estável, e cada uma tem uma página explicativa em 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"]
}

O suggested_fix é escrito como uma frase que um LLM pode ler diretamente para decidir a próxima ação — o padrão recomendado é passar a mensagem de exceção inteira para o loop do agente. O SDK lança exceções com o suggested_fix incluído, e a CLI imprime a mesma frase no stderr.

type	Status típico	Significado
validation	400 / 422	A entrada não cumpre o contrato (falha de SQL, nome proibido, referência hard-coded no template etc.)
propagation-failed	400	A transformação foi salva e materializada; em seguida, a reconstrução de uma transformação downstream falhou
unauthorized	401	PAT ausente, inválido ou revogado
forbidden	403	Scope insuficiente, recusa por política (mask / deny), fora do scope do workbook
unknown-workbook	404	O workbook não existe ou não está visível
unknown-artifact	404	A tabela / o artifact não existe, ou é de um tipo não exposto em /api/v1
conflict	409	Lock otimista (expected_version defasado), workbook em processamento, nome duplicado
rate-limited	429	Rate limit atingido. Siga o Retry-After
internal	5xx	Falha do lado do servidor. Entre em contato informando o trace_id

5xx e trace_id

Respostas 5xx usam o mesmo problem+json. O trace_id (também no header X-D2B-Trace-Id) corresponde 1:1 ao stack trace do servidor — inclua-o ao reportar. Jobs de ingest assíncrono que falharam também carregam trace_id e a fase da falha (phase).

Para superfícies onde o vocabulário REST (GET /api/...) não se encaixa, os erros aplicáveis também trazem suggested_fix_cli (vocabulário d2b ...). A CLI exibe essa variante automaticamente.