API 에러 응답도 표준이 있다? RFC 9457로 깔끔하게 처리

 

API 연동 작업을 하다 보면 이런 에러 응답, 한 번쯤 받아봤을 것이다.

{
  "message": "Invalid request"
}

 

이런 에러 발생시에 어떻게 처리해야할지 발생시마다 백엔드에 물어보거나, 로그를 뒤져보거나, 요청 데이터를 찍어보는 등 불필요한 시간낭비를 할때가 종종있다. 

 

이런 비효율적인 커뮤니케이션을 줄이기 위해, 에러 응답 구조를 표준화한 RFC 9457을 사용하면 백엔드와 프론트엔드 사이의 불필요한 확인 작업을 크게 줄일 수 있다.

 

RFC 9457이 뭔데?

간단히 말해, HTTP API의 에러 응답을 표준 JSON 포맷으로 구조화하자는 문서.
이전엔 RFC 7807이라는 게 있었고, RFC 9457은 그걸 확장한 버전이다.

 

주요 필드로는,

• type: 오류 유형을 식별하는 URI. 예: https://example.com/probs/out-of-credit
• title: 오류의 간단한 설명. 예: "You do not have enough credit."
• status: HTTP 상태 코드. 예: 403
• detail: 오류에 대한 자세한 설명. 예: "Your current balance is 30, but that costs 50."
• instance: 오류가 발생한 특정 인스턴스를 식별하는 URI. 예: "/account/12345/msgs/abc"

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "status": 403,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc"
}

 

프론트엔드 입장에서 이런 구조화된 정보가 왜 좋냐면:

• status로 어떤 에러인지 바로 파악할 수 있고,
• title, detail로 사용자에게 적절한 메시지를 띄우기 쉬우며,
• type 값으로 에러 종류별 분기 처리(예: validation, 인증 실패 등)가 가능.

 

RFC 9457 응답이 들어오면, 프론트단에서는 다음과 같은 패턴으로 활용할 수 있다.

 

// 예: 에러 응답 처리 함수
function handleApiError(error: any) {
  if (error.response?.data?.type === 'https://example.com/probs/validation') {
    // 유효성 검사 에러 처리
    showFormErrors(error.response.data.invalidFields);
  } else {
    showToast(error.response?.data?.title || '예상치 못한 오류가 발생했습니다.');
  }
}

 

이처럼 type, title, detail 등을 기준으로 재사용 가능한 에러 처리 UI를 만들 수 있다는 것.

에러 응답도 결국 API의 중요한 일부라고 생각한다.
어떻게 에러를 정의하고 전달하느냐에 따라 개발자 경험뿐 아니라 사용자 경험까지도 확실히 달라질 수 있다.

참고자료 : 
RFC 9457 공식 문서

RFC 9457: Problem Details for HTTP APIs

 

Swagger 블로그: RFC 9457을 활용한 API 오류 처리

 

Redocly 블로그: RFC 9457의 개선 사항