에러 읽는 법

에러는 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	scope 부족, 정책(mask / deny)에 의한 거부, workbook scope 밖
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 는 자동으로 그쪽을 표시합니다.