[Spring] API 응답에서 직접 정의한 Error code 는 왜 사용할까?

직접 정의한 Error code 란?

직접 정의한 에러코드는 HTTP Status code 와 별개로 정의한 에러코드를 의미한다. HTTP 응답에는 HTTP 요청이 성공했는지 실패했는지 나타내주는 HTTP Status code 가 존재함에도, 대부분의 서비스에서는 아래처럼 HTTP Status code 뿐만 아니라 직접 정의한 Error code 도 함께 내려준다.

 

[카카오 쇼핑 에러코드]

응답 코드 및 에러 코드

[카카오뱅크 에러코드]

간편하고 다양한 인증이 필요할때 카카오뱅크 인증서

[Naver Cloud Platform 에러코드]

CLOVA eKYC 에러코드

[NHN CLOUD]

오류 코드 - NHN Cloud 사용자 가이드

 

이렇게 에러코드를 직접 정의하면 REST API의 에러 응답을 이해하기 위해 API 문서에 작성하고, 확인해야한다는 단점이 있다.

직접 정의한 Error code 를 사용하는 이유

그럼에도 불구하고 직접 정의한 Error code를 사용하는 이유는 무엇일까?

예시로, 주문 내 상품을 확인하는 다음과 같은 엔드포인트를 가정해본다.

/api/v2/orders/{orderId}/items/{productId}

• 주문이 존재하지 않을 경우 404 (Not Found) 를 내려준다.
• 주문 내 상품이 존재하지 않을 경우 404 (Not Found) 를 내려준다.
• 상품의 재고 정보가 존재하지 않을 경우 404 (Not Found) 를 내려준다.

이때 동일한 404 Status Code를 반환하는 예외가 다수 존재한다. 이 경우 클라이언트에서 어떤 예외인지에 따라 다르게 처리하기 위해서는 상태 코드 뿐만아니라 추가적인 정보가 필요하다.

 

결국, 직접 정의한 Error code 가 없다면 Error message 를 참고해서 처리해야 하는데, Error message 는 대부분 사람이 이해할 수 있는 문자열 형식으로 서버에서 오탈자 수정, 내용변경 등 에러 메시지 내용을 변경하는 상황이 발생할 가능성이 높다. 이 경우 클라이언트에서 예외 처리 로직이 깨질 가능성이 높아지므로, 별도 ErrorCode 를 정의해 응답 본문에 추가해주는 것이다.

 

그러면, ErrorCode 는 어떻게 만들어야 하는가?

위에서 첨부한 카카오,네이버,NHN 등의 예시만 보더라도 에러코드에 대한 양식은 모두 상이하다. 딱 이렇게 만들어라는 규칙은 없다.

중요한 것은 해당 API 를 사용하는 클라이언트 측에서 에러 코드가 무슨 역할을 하고, 어떠한 상황에서 이 에러가 발생했는지에 대한 원인이 기술되어 있어야 한다는 것이다.

1. 에러 코드
2. 에러코드가 어떤 에러 상황에서 발생했는지에 대한 설명
3. 매핑되는 HTTP 상태코드 (선택)

따라서 API 를 제공하는 쪽에서는 수동 문서화 또는 REST DOCS, Swagger (description) 등 문서화 툴을 활용해 에러코드에 대한 용어사전을 정의하는 것이 좋다.

 

에러코드에 대한 예시를 추가하면 필자의 경우 웹계층에서 발생한 에러와 비즈니스 처리과정에 대한 에러코드를 다음과 같이 나누었다. 각자 에러의 성격이 다르다 보았고 각 계층의 책임을 명확히 구분하고 관리하자는 생각에서 나눈 것이다. 앞에 E 를 추가한 이유는 http 상태코드도 세자리이므로 클라이언트의 혼동을 줄이기 위해서 붙였다. 

// 웹계층에서 발생한 에러 1XX 시작
public enum ApiErrorCode {
    E100,
    E101,
    E102,
    E103,
    E104,
}

// 비즈니스 처리 과정에서 발생한 에러 4XX 시작
public enum CoreErrorCode {
    E401,
    E402,
    E403,
    E404,
    E405
}

• 웹 계층(ApiErrorCode): 클라이언트와의 통신 과정에서 발생하는 오류 ex) 잘못된 요청, 파라미터 누락, 인증 실패 등
• 비즈니스 로직 계층(CoreErrorCode): 도메인 로직에서 발생하는 오류 ex) 주문 실패, 재고 부족 등