Error Handling in HTTP APIs

에러 처리는 왜 설계 대상인가

API를 설계할 때 성공 응답만 정의하고 에러 응답을 나중으로 미루면, 클라이언트와 운영자가 가장 자주 보게 되는 실패 상황이 오히려 제일 불명확해진다.

좋은 에러 응답은 다음 역할을 해야 한다.

• 클라이언트가 재시도 가능 여부를 판단하게 한다.
• 잘못된 요청인지, 서버 장애인지 구분하게 한다.
• 운영자가 로그와 모니터링에서 빠르게 원인을 찾게 한다.

최소한 맞춰야 할 것

• 적절한 HTTP 상태 코드
• 일관된 응답 포맷
• 사람이 읽을 수 있는 메시지
• 기계가 분기할 수 있는 에러 코드
• 요청 추적용 식별자

상태 코드를 어떻게 쓸까

• 400: 요청 자체가 잘못됨
• 401: 인증되지 않음
• 403: 권한 없음
• 404: 리소스 없음
• 409: 상태 충돌
• 422: 의미는 맞지만 비즈니스 검증 실패
• 500: 서버 내부 오류
• 503: 일시적 장애 또는 의존 시스템 문제

실패를 모두 400이나 500으로 뭉개면 클라이언트도, 운영자도 판단이 어려워진다.

실무에서 중요한 포인트

검증 오류와 시스템 오류를 분리

사용자 입력 오류와 서버 장애는 전혀 다른 종류의 실패다. 응답 구조, 로그 레벨, 알람 기준도 달라야 한다.

내부 예외를 그대로 노출하지 않기

스택 트레이스나 DB 오류 원문을 클라이언트에 그대로 보내면 보안과 사용자 경험 모두에 좋지 않다.

실패도 계약으로 관리

성공 응답만 API 계약이 아니다. 프론트엔드나 외부 연동 시스템은 실패 응답도 계약으로 소비한다.

Problem Details 같은 표준

에러 응답 포맷을 직접 정의할 수도 있지만, 가능하면 Problem Details 같은 표준 형식을 쓰는 편이 좋다. 팀이 커질수록 예외 응답의 일관성이 중요해지기 때문이다.

정리

에러 처리는 예외 상황을 덧붙이는 작업이 아니라 API 품질을 결정하는 핵심 설계다. 성공 응답만큼 실패 응답도 명확해야 시스템이 운영 가능해진다.