31장. API 오류를 Problem Details로 통일한다

오류 response는 사용자가 고칠 수 있는지, 재시도할지, support에 무엇을 전달할지 알려야 한다. validation은 field path와 안정적인 code를 포함하고 번역 문구를 contract key로 쓰지 않는다. authentication 401과 authorization 403, 없는 자원 404, version 충돌 409, rate limit 429를 구분한다. 존재 여부가 민감한 자원은 정책에 따라 404로 감출 수 있다.

{
  "type": "https://crewlink.example/problems/high-risk-unacknowledged",
  "title": "확인하지 않은 고위험 항목이 있습니다",
  "status": 409,
  "instance": "/handoffs/hf-2048",
  "correlationId": "req-7f31",
  "code": "HIGH_RISK_UNACKNOWLEDGED"
}

예외 handler는 예상 domain error만 구체적으로 변환한다. 알 수 없는 exception은 stack·SQL·token을 response에 넣지 않고 500과 correlation id를 돌린다. contract test는 content type, status, 필수 field, 민감 정보 부재를 확인한다. proxy와 application이 서로 다른 오류 형태를 만들지 않게 gateway contract도 포함한다.