애플리케이션 에러 코드 설계

이슈

  • http status code와 분리된 애플리케이션 레벨의 에러코드가 필요
  • 예를 들어, http status code 500 에러 발생 시 애플리케이션 내부적으로 어떤 에러가 발생했는지 http status code만 보고 파악하기 어렵기 때문에
  • 애플리케이션 에러의 형식을 정의하여 관리를 용이하게 하기 위해서도 필요
  • End-user보다는 개발자의 트러블 슈팅을 위한 것
  • Application level 에러 코드에 대해서는 정확히 표준이 없어서 애플리케이션마다 구조가 상이

좋은 애플리케이션 레벨 에러 디자인 패턴

  • 에러상황에 맞는 적절한 HTTP status code를 리턴하는 데 우선 집중할 것.
    • 애플리케이션 레벨 에러는 하나의 HTTP status code 안에서 세부적으로 에러를 구분하기 위한 목적이므로
  • HTTP status code와 별개로 Response body를 활용한다.
    • 애플리케이션 레벨 코드로 HTTP status code를 혼용해서 쓰지 않는다.
  • 하나의 애플리케이션 레벨 코드는 하나의 HTTP status code에만 종속되도록 한다. (M:N이 되지 않도록)
  • 단순 에러코드만 리턴하지 않고 human-readable한 정보를 포함하도록 한다

image-20210422143359681

  • 에러코드는 꼭 Integer type일 필요는 없다.
    • 알파벳을 포함할수도 있고, error code라는 enumeration을 정의하여 활용할 수도 있다
  • 운영 환경에서는 보안에 유의할 것
    • 운영 시 일반적인 서비스 구조에서는 에러 스택정보를 API 에러 메세지에 포함 시키지 않는 것이 바람직 하다. 옵션에 따라 dev 모드등으로 기동시, REST API의 에러 응답 메세지에 에러 스택 정보를 포함해서 리턴하도록 하면, 디버깅에 매우 유용하게 사용할 수 있다.

여러가지 예시

1. IETF 표준

  • REST API의 에러 핸들링의 표준화를 위해서 RFC 7807에서 제시한 에러핸들링 일반 구조.
    • 제시만 했을 뿐 표준화가 되진 않았다.
  • 총 5개의 필드로 구성
    1. type : 세부 에러 코드. (꼭 숫자일 필요는 없음)
    2. title : 에러에 대한 간략한 설명
    3. status(optional) : HTTP response code
    4. detail : 에러에 대한 자세한 설명
    5. instance : 에러 발생 근원지 URI
  • 예시
{
    "type": "/errors/incorrect-user-pass",
    "title": "Incorrect username or password.",
    "status": 401, 
    "detail": "Authentication failed due to incorrect username or password.",
    "instance": "/login/log/abc123"
}




{
    "status":"401",
    "message":"Authenticate",
    "code":"200003",
    "more info":"http://www.twillo.com/docs/errors/20003"
}




3. Trace id 포함

  • 애플리케이션에서 로깅에 사용한 trace id를 error response body안에 담고 후에 트러블슈팅할 때 해당 아이디를 로깅 시스템에서 조회할 수 있도록한다.
  • 직접적인 에러 정보를 노출하지 않기 때문에 보안에 유리
  • Facebook Graph API의 fbtrace_id
    {
        "message": "Missing redirect_uri parameter.",
        "type": "OAuthException",
        "code": 191,
        "fbtrace_id": "AWswcVwbcqfgrSgjG80MtqJ"
    }
    

References

Leave a comment