API 설계를 하다 보면 한 가지 고민이 생긴다.

에러 응답 시 HttpStatus만 주면 될텐데 왜 굳이 code(커스텀 에러 코드)를 추가로 주는 걸까?

나도 이전 프로젝트 최종 발표 중에 이 부분에 대해 피드백을 받았고, 여러 실무 사례와 자료를 찾아보며 정리해보았다.

🚀 왜 code 를 주냐? → 주된 목적은 "프론트 단 에러 핸들링 규칙화 + 추적성 확보"

1️⃣ 프론트 핸들링 시 안정성

프론트가 "message" (한국어 메시지) 기반으로 핸들링 하면 → 나중에 다국어, 메시지 변경 시 위험.

{
  "code": "USER-001",
  "message": "인증 코드가 만료되었습니다.",
  "httpStatus": 401
}

위와 같이 응답이 오게되면
→ 프론트에서는 아래처럼 code를 기준으로 에러 처리 분기를 편리하게 적용할 수 있게 된다.

if (error.code === 'USER-001') {
    showToast("인증 코드를 다시 입력해 주세요.");
} else if (error.code === 'USER-002') {
    showToast("인증 코드가 일치하지 않습니다.");
}
→ 안정적 → message 변경돼도 프론트는 깨지지 않음

2️⃣ 로그 추적성 / 모니터링

서버 로그나 모니터링 시스템에서 code 기반으로 에러를 모니터링 할 수 있다.

로깅 예시 :

[ERROR] USER-001 발생 → 알람 전송
[ERROR] ORDER-005 발생 → 재고 없음

→ 정확히 어떤 에러인지 추적 가능 (message는 다국어/버전별로 바뀔 수 있음)

3️⃣ 에러 명세서 관리 (Error Spec)

API 명세서에 Error Spec 별도 관리하면 팀원들과 api 응답에 관하여 함께 이해할 수 있게 된다.

Code	Message	HttpStatus	Description
USER-001	인증 코드가 만료되었습니다.	401	인증코드 만료 시 발생
ORDER-001	재고가 부족합니다.	400	주문 시 재고 부족 발생

-> 클라이언트팀 + QA팀 + 서버팀 다 공유
-> 클라이언트는 이 문서를 보고 "아 USER-001은 인증 코드 만료구나" 라고 이해
-> 문서로 작성하며 계속해서 추가해두는 것이 좋다.

---

Enum 구조 설정

✅ 기존 구조

@Getter
@RequiredArgsConstructor
public enum UserErrorStatus implements BaseErrorCode {
    EXPIRED_AUTH_CODE("USER-401", "인증 코드가 만료되었습니다.", HttpStatus.UNAUTHORIZED),
    MISS_MATCH_AUTH_CODE("USER-403", "인증 코드가 일치하지 않습니다.", HttpStatus.BAD_REQUEST);

    private final String code;
    private final String message;
    private final HttpStatus httpStatus;
}

기존에는 커스텀 코드를 제공하지 않았었고, HttpStatus에 맞게 도메인명의 뒤에 추가적으로 상태코드를 붙여주려고 하였다.

✅ 현재 구조

@Getter
@RequiredArgsConstructor
public enum UserErrorStatus implements BaseErrorCode {
    EXPIRED_AUTH_CODE("USER-001", "인증 코드가 만료되었습니다.", HttpStatus.UNAUTHORIZED),
    MISS_MATCH_AUTH_CODE("USER-002", "인증 코드가 일치하지 않습니다.", HttpStatus.BAD_REQUEST);

    private final String code;
    private final String message;
    private final HttpStatus httpStatus;
}

"USER" → 도메인 prefix

"001","002" → 커스텀 숫자

---

❌ 실무에서 문제로 지적되는 부분

1️⃣ HTTP 상태코드와 비즈니스 커스텀 에러코드는 다른 레이어

HttpStatus.UNAUTHORIZED (401) → 통신 수준 상태 코드

USER-001 → 비즈니스 로직에서 발생한 고유 에러 코드

→ 둘을 잘못 섞으면 개념적으로 혼란이 발생하므로 USER-400, 401이 아닌 차근차근 커스텀 코드를 준다.

2️⃣ 문제점

🚩 혼용된 코드명 → 유지보수 리스크 발생

1. 프론트에서 헷갈림
   code = USER-401 → 이게 USER-001부터 차례대로 올라간 USER-401을 의미하는 건지, 그냥 401 UNAUTHORIZED 에러 코드인지 모호하다.

2. 유지보수 위험
   나중에 HttpStatus 변경 시 code 값도 바꿔야 할까?

예: USER-401 → 403으로 바꾸면 USER-403?
→ 유지보수가 모호하다.

---

🚀 실무에서 추천하는 패턴

✅ 비즈니스 코드와 HttpStatus 완전 분리

USER-401 처럼 HttpStatus와 섞은 코드 : ❌ 비추천, 코드 강결합 발생, 유지보수 어려움
USER-001 처럼 고유 비즈니스 코드 사용 : ✅ 추천, 비즈니스 코드 독립적, HttpStatus와 분리, 유지보수 용이

✅ 왜 이렇게 할까?

HttpStatus는 변경 가능성 있음 (Ex. 401 → 403 변경 가능)
비즈니스 커스텀 코드는 고유/불변! API 명세서에 "정의된 코드"로 동작해야 함
-> 프론트에서는 보통 code 기준으로 에러 핸들링 로직을 작성할 수 있다.
-> 팀원들 모두 확인할 수 있도록 에러 명세서를 관리해야 한다!!

---