Api-Design

개요 HTTP Status Code만으로는 서비스 로직의 원인을 전달하기 부족함 400대와 500대는 네트워크 관점의 대분류 신호에 가깝고 실제로 필요한 것은 비즈니스 맥락의 구체적 사유임 결론은 단순함 HTTP Status는 대분류 신호로 두고 실제 의미와 추가 컨텍스트는 Response Body에 싣는 구조가 현실적 해법임 핵심 원칙 HTTP Status는 큰 범주 신호등 역할 2xx 성공 4xx 클라이언트 오류 5xx 서버 오류 비즈니스 의미는 Response Body의 커스텀 에러 구조로 표현 클라이언트가 코드 기반으로 분기하고 UI를 결정할 수 있어야 함 운영 관측을 위해 traceId 제공 업계에서 검증된 기본 구조 아래 형태가 가장 보편적으로 쓰이는 패턴임 ...

개요 API 에러 규격의 핵심은 에러를 안정적으로 식별할 수 있는 Code 체계 확보임 HTTP Status만으로는 부족하고 메시지는 언어·맥락에 따라 바뀔 수 있음 실제로 계약으로서 신뢰할 수 있는 값은 error.code 임 아래는 다수의 글로벌 서비스에서 공통적으로 쓰는 Error Code 설계 원칙 정리 설계 원칙 error.code 는 서비스 전반의 안정적인 식별자여야 함 메시지나 HTTP Status는 변경 가능하지만 error.code 는 변경 불가 구버전 클라이언트도 동일 코드를 신뢰해야 하므로 호환성 보장 필수 숫자형 대신 의미가 드러나는 문자열 기반 Enum 권장 숫자형은 의미 파악 어려움, 매뉴얼 의존, 협업 비용 증가 문자열 Enum은 가독성, 검색성, 커뮤니케이션 효율 우수 예시 ...