요약

  • 2016년 3월의 RFC 7807은 HTTP API 오류의 공통 JSON·XML 형식을 정의했다. 기계가 오류 종류를 구별할 때 쓰는 기본 식별자는 처음부터 type URI였다.
  • 2023년 7월의 RFC 9457은 이를 대체하면서 상대 URI의 혼동, 주소 변경이 낳는 호환성 문제, 여러 오류를 다루는 기준을 더 분명히 했다.
  • IANA의 공식 등록부는 공통으로 재사용할 오류 종류를 담는다. type이 없으면 about:blank가 적용돼 HTTP 상태 이상의 의미를 주장하지 않는다.

403이라는 답장에 빠진 한 줄

프록시나 범용 클라이언트는 403만으로 요청이 거부됐음을 안다. 쇼핑 프로그램은 부족한 잔액과 다른 금지 규칙을 구분해야 다음 행동을 정할 수 있다. 모든 사업상의 실패에 새 HTTP 상태 코드를 만들면 공통 프로토콜이 각 회사의 장부가 된다. RFC 7807은 상태 코드에 넓은 판정을 맡기고, 응답 본문에 애플리케이션의 구체적인 사유를 싣는 분업을 선택했다.

규격의 예시에서는 구매가 403으로 거절되고, 본문은 잔액 부족이라는 종류, 사람이 읽을 제목, 이번 사건의 설명, 발생 건을 가리키는 instance, 잔액과 계정에 관한 확장 필드를 담는다. application/problem+json이라는 그릇은 공통이고 XML 표현도 정의됐다. 그러나 어느 상황을 잔액 부족으로 부를지, 고객에게 어떤 선택지를 줄지는 그 API를 제공하는 기관이 정한다. 표준은 자리를 만들었지 각 업체의 운영 규칙을 작성하지 않았다.

클라이언트가 의지해야 할 필드는 type이다. 2016년 문서는 이 URI를 문제 종류의 주요 식별자로 쓰도록 했다. title은 사람을 위한 짧은 문구라 언어에 따라 달라질 수 있다. detail은 이번 사건을 설명하는 문장이다. 프로그램이 그 문장에서 “잔액”이라는 단어를 찾아 결정을 내리면 번역이나 문구 수정에 행동이 흔들린다. URI를 인식하는 설계는 운영자가 그 이름의 뜻을 지켜 준다는 명시적인 약속에 기댄다.

instance는 오류 종류가 아니라 발생 건을 가리킨다. 두 번의 구매가 모두 잔액 부족이어도 각각 다른 사건 주소를 가질 수 있다. 고객 지원은 개별 사건을 추적하고, 클라이언트는 같은 종류에 같은 처리 규칙을 적용한다. 두 필드를 막연히 “오류 ID”라고 부르면 이 중요한 구분이 사라진다.

빈칸에도 경계가 있다

type이 빠지면 값은 about:blank로 간주된다. 이름 그대로 정보가 적다. 그 문제는 HTTP 상태 코드보다 더 구체적인 뜻을 갖지 않는다. 404를 JSON 형식으로 감쌌다고 해서 새 오류 종류가 생기지는 않는다. 운영자가 두 가지 403을 구별시키려면 스스로 이름을 만들고, 설명하고, 유지해야 한다.

본문의 status 역시 실제 HTTP 상태를 대신하지 않는다. 값을 넣었다면 응답 상태와 같아야 한다. 중간 장치가 값을 바꾸거나 기록에서 응답 머리 부분이 빠질 수 있지만, 범용 HTTP 소프트웨어는 전송된 상태 코드를 따른다. 자세한 본문은 그 위에 놓이는 정보다.

주소를 옮기면 종류도 바뀐다

RFC 9457은 2023년 기존 구조를 이어받으며 URI 선택의 비용을 구체적으로 적었다. example-problem 같은 상대 주소는 응답의 기준 URL에 따라 다른 자원으로 해석될 수 있다. 같은 글자라도 다른 오류를 가리키게 되는 셈이다. 그래서 가능하면 절대 URI를 쓰라고 권한다.

열리지 않는 URI도 식별자로 쓸 수 있다. 훗날 설명 문서를 보여 주려고 열리는 URL로 바꾸면 기계에겐 새 오류 종류가 된다. 오래된 클라이언트가 같은 실패를 알아보지 못할 수 있다. 처음에 편하게 붙인 이름이 장기간 호환성 비용으로 되돌아온다.

개정판은 여러 문제가 한 번에 나타날 때의 순서도 정리했다. 같은 검증 문제 안의 여러 입력 오류는 확장 필드로 나열할 수 있다. 종류가 서로 다르면 가장 관련 있거나 긴급한 하나를 드러내라고 권한다. 하나의 HTTP 응답에는 하나의 주된 상태가 있기 때문이다. IANA 등록부는 널리 공유할 종류에 규격을 요구한다. 개별 업체의 오류 명칭은 그 업체가 계속 책임진다.

실제 보급 범위를 알려면 날짜가 남은 서버 응답과 클라이언트 출시 기록이 더 필요하다. 두 RFC만으로도 책임의 위치는 확인된다. 표준화 기구가 형식을 만들고, 각 API 운영자가 자신이 붙인 이름을 지킨다.