エラーの読み方

エラーは RFC 7807 風の application/problem+json で返ります。type は安定した識別子 URI で、それぞれ 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 がそのまま読んで次の行動を決められる文で書かれています — エージェントのループに例外メッセージごと渡すのが推奨パターンです。SDK は suggested_fix 込みの例外を投げ、CLI は同じ文を stderr に出します。

type	典型的な status	意味
validation	400 / 422	入力が契約に合わない(SQL の失敗、名前の禁則、テンプレートのハードコード参照など)
propagation-failed	400	変換の保存と実体化は成功したが、その後に下流変換の再構築が失敗
unauthorized	401	PAT が無い・無効・失効
forbidden	403	スコープ不足、ポリシー(mask / deny)による拒否、workbook スコープ外
unknown-workbook	404	workbook が無い、または見えない
unknown-artifact	404	テーブル / アーティファクトが無い、または /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 にも同値)がサーバ側のスタックトレースと 1:1 に対応するので、問い合わせにはこの値を添えてください。非同期 ingest の失敗は job レコードにも trace_id と失敗フェーズ(phase)が載ります。

REST 語彙(GET /api/...)が合わない面のために、該当エラーは suggested_fix_cli(d2b ... 語彙)も併送します。CLI は自動でそちらを表示します。