Skip to content

BE Error Convention

wcorn edited this page Apr 2, 2026 · 1 revision

BE 에러 처리 컨벤션

에러 코드 체계와 예외 처리 흐름을 정의한다.

1. 응답 형식

성공 응답

{
  "code": "요청에 성공하였습니다.",
  "data": { ... }
}
  • ApiResponse.success(data) 또는 ApiResponse.success()로 생성
  • code는 CustomResponseCode.SUCCESS의 메시지

에러 응답

{
  "code": "AUTH-ERR-001",
  "message": "아이디 또는 비밀번호가 올바르지 않습니다."
}
  • ErrorResponse.of(errorCode)로 생성
  • code는 에러 코드 문자열, message는 사용자 메시지

2. 에러 코드 네이밍 규칙

{모듈}-ERR-{번호}
구성 규칙 예시
모듈 대문자 약어 (3~4자) GLB, AUTH, SP
ERR 고정 문자열 ERR
번호 3자리, 모듈 내 순차 001, 002

모듈 접두사

접두사 모듈 설명
GLB Global 공통 에러 (400, 405, 500 등)
AUTH Auth 인증/인가 에러
새 모듈 추가 시 - 약어를 정하고 ErrorCode enum에 주석 구분

3. 예외 처리 흐름

비즈니스 로직에서 throw new CustomException(ErrorCode.XXX)
    ↓
GlobalExceptionHandler가 catch
    ↓
ErrorCode에서 HTTP 상태 코드 + 에러 코드 + 메시지 추출
    ↓
ErrorResponse로 변환 → HTTP 응답

GlobalExceptionHandler 처리 순서

예외 매핑 에러 코드 HTTP 상태
CustomException 예외에 포함된 ErrorCode ErrorCode의 httpStatus
MethodArgumentNotValidException GLB-ERR-001 400
MethodArgumentTypeMismatchException GLB-ERR-001 400
HttpRequestMethodNotSupportedException GLB-ERR-002 405
Exception (기타) GLB-ERR-003 500

4. 에러 코드 추가 방법

1단계: ErrorCode enum에 추가

// {모듈}
NEW_ERROR("{MOD}-ERR-{NNN}", "사용자에게 보여줄 메시지.", {httpStatus}),
  • 같은 모듈의 에러끼리 모아서 주석으로 구분
  • HTTP 상태 코드를 정수로 지정

2단계: 비즈니스 로직에서 사용

throw new CustomException(ErrorCode.NEW_ERROR);
  • 추가 컨텍스트가 필요하면 new CustomException(ErrorCode.NEW_ERROR, cause) 사용

추가하지 않아도 되는 경우

  • Validation 에러: @Valid로 처리, GLB-ERR-001로 자동 매핑
  • 메서드 미지원: GLB-ERR-002로 자동 매핑
  • 예상치 못한 에러: GLB-ERR-003으로 자동 매핑

5. 설계 규칙

  • 에러 코드는 클라이언트가 분기에 사용한다 — 메시지가 아닌 코드로 에러를 식별
  • 메시지는 사용자에게 보여줄 수 있는 문장으로 작성한다 — 기술적 디버그 정보는 로그에만
  • 같은 의미의 에러 코드를 중복 생성하지 않는다 — 기존 코드를 먼저 확인
  • ErrorCode enum은 orino-common 모듈에 위치한다 — 모든 모듈에서 참조 가능
  • GlobalExceptionHandler는 orino-core-web 모듈에 위치한다 — 도메인 비즈니스를 모름

Clone this wiki locally