API 오류 응답 형식을 정리하며 배운 점

API를 만들다 보면 성공 응답보다 오류 응답을 더 자주 고민하게 됩니다. 상태 코드만으로 충분한지, 사용자에게 보여줄 메시지는 어디에서 결정할지 같은 문제가 반복해서 등장합니다.

응답에 포함한 정보

이번에는 모든 오류가 같은 구조를 사용하도록 정리했습니다.

{
  "code": "ORDER_NOT_FOUND",
  "message": "주문을 찾을 수 없습니다.",
  "path": "/api/orders/42"
}

• code는 클라이언트가 분기 처리할 때 사용합니다.
• message는 개발 중 원인을 빠르게 파악할 수 있도록 간결하게 작성합니다.
• path는 로그와 요청을 연결할 때 활용합니다.

남은 고민

사용자에게 그대로 보여줄 문구와 내부 디버깅 메시지를 한 필드에 담으면 변경하기 어려워집니다. 앞으로는 사용자 메시지를 클라이언트에서 관리하고 서버는 안정적인 오류 코드만 제공하는 방향도 검토할 예정입니다.

오류 응답의 목표는 정보를 많이 제공하는 것이 아니라, 다음 행동을 예측할 수 있게 만드는 것입니다.