如何读懂错误

错误以 RFC 7807 风格的 application/problem+json 返回。type 是稳定的标识符 URI,每个 type 在 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 是按 LLM 可以直接读懂并决定下一步行动的句子来撰写的 — 推荐的模式是把异常消息整个传回 Agent 的循环。SDK 抛出带 suggested_fix 的异常,CLI 把同样的文本输出到 stderr。

type	典型 status	含义
validation	400 / 422	输入不符合契约(SQL 执行失败、名称触犯命名限制、模板中硬编码引用等)
propagation-failed	400	变换已保存并物化，但随后下游变换的重建失败
unauthorized	401	没有 PAT、无效或已失效
forbidden	403	scope 不足、被策略(mask / deny)拒绝、超出 workbook scope
unknown-workbook	404	workbook 不存在,或不可见
unknown-artifact	404	表 / artifact 不存在,或该类型未暴露在 /api/v1
conflict	409	乐观锁(expected_version 不一致)、workbook 正在处理中、名称重复
rate-limited	429	触发速率上限。遵循 Retry-After
internal	5xx	服务器侧的失败。请附上 trace_id 联系我们

5xx 与 trace_id

5xx 也返回同样的 problem+json。trace_id(响应头 X-D2B-Trace-Id 中同值)与服务端堆栈一一对应 — 反馈问题时请附上。异步 ingest 失败的 job 记录同样携带 trace_id 与失败阶段(phase)。

对于 REST 词汇(GET /api/...)不适用的界面,相关错误还会附带 suggested_fix_cli(d2b ... 词汇)。CLI 会自动显示该版本。