Repository navigation
BE Error Convention
wcorn edited this page Apr 2, 2026
·
1 revision
에러 코드 체계와 예외 처리 흐름을 정의한다.
{
"code": "요청에 성공하였습니다.",
"data": { ... }
}-
ApiResponse.success(data)또는ApiResponse.success()로 생성 -
code는CustomResponseCode.SUCCESS의 메시지
{
"code": "AUTH-ERR-001",
"message": "아이디 또는 비밀번호가 올바르지 않습니다."
}-
ErrorResponse.of(errorCode)로 생성 -
code는 에러 코드 문자열,message는 사용자 메시지
{모듈}-ERR-{번호}
| 구성 | 규칙 | 예시 |
|---|---|---|
| 모듈 | 대문자 약어 (3~4자) |
GLB, AUTH, SP
|
| ERR | 고정 문자열 | ERR |
| 번호 | 3자리, 모듈 내 순차 |
001, 002
|
| 접두사 | 모듈 | 설명 |
|---|---|---|
GLB |
Global | 공통 에러 (400, 405, 500 등) |
AUTH |
Auth | 인증/인가 에러 |
| 새 모듈 추가 시 | - | 약어를 정하고 ErrorCode enum에 주석 구분 |
비즈니스 로직에서 throw new CustomException(ErrorCode.XXX)
↓
GlobalExceptionHandler가 catch
↓
ErrorCode에서 HTTP 상태 코드 + 에러 코드 + 메시지 추출
↓
ErrorResponse로 변환 → HTTP 응답
| 예외 | 매핑 에러 코드 | 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 |
// {모듈}
NEW_ERROR("{MOD}-ERR-{NNN}", "사용자에게 보여줄 메시지.", {httpStatus}),- 같은 모듈의 에러끼리 모아서 주석으로 구분
- HTTP 상태 코드를 정수로 지정
throw new CustomException(ErrorCode.NEW_ERROR);- 추가 컨텍스트가 필요하면
new CustomException(ErrorCode.NEW_ERROR, cause)사용
- Validation 에러:
@Valid로 처리,GLB-ERR-001로 자동 매핑 - 메서드 미지원:
GLB-ERR-002로 자동 매핑 - 예상치 못한 에러:
GLB-ERR-003으로 자동 매핑
- 에러 코드는 클라이언트가 분기에 사용한다 — 메시지가 아닌 코드로 에러를 식별
- 메시지는 사용자에게 보여줄 수 있는 문장으로 작성한다 — 기술적 디버그 정보는 로그에만
- 같은 의미의 에러 코드를 중복 생성하지 않는다 — 기존 코드를 먼저 확인
- ErrorCode enum은 orino-common 모듈에 위치한다 — 모든 모듈에서 참조 가능
- GlobalExceptionHandler는 orino-core-web 모듈에 위치한다 — 도메인 비즈니스를 모름