11 KiB
title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
| title | source_type | url | archive_url | status | confidence | tags | related_projects | related_branches | created | last_reviewed | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| RFC 7807 Problem Details for HTTP APIs | official-doc | https://datatracker.ietf.org/doc/html/rfc7807 | reviewed | high |
|
|
|
2026-05-22 | 2026-05-27 |
RFC 7807 — Problem Details for HTTP APIs
Layer:
raw/official-docs/— IETF RFC 7807 의 HTTP API error envelope 표준. ca-tmpl 이 명시적으로 forbidden 으로 둔 표준 — 채택 안한 결정의 trade-off 평가 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-operational-error-observability-foundation | ca-tmpl custom envelope vs RFC 7807 ProblemDetail 채택 결정의 표준 reference |
| raw/branch-notes/feature-boundary-validation-mapping-contract | boundary validation error 시 응답 shape 결정 (RFC 7807 미채택 근거) |
| raw/branch-notes/feature-business-rule-validation-contract | business rule violation 응답 shape 결정 (RFC 7807 미채택 근거) |
| raw/project-notes/ca-skeleton-operational-contract | §3. Structured API Response Contract + §6. Operational Error Category — 미채택 표준 reference |
컨텍스트 / 왜 저장했는지
ca-tmpl 이 명시적으로 forbidden 으로 둔 표준. custom envelope ({success, data, error.{code,category,message,retryable,details}, meta}) 결정의 trade-off 를 평가하려면 표준의 정확한 shape, 확장 메커니즘, 한계를 먼저 알아야 함. RFC 7807 은 현재 RFC 9457 로 obsolete 되었으나 본 문서는 7807 기준 정리.
출처 / Source
- 원본 URL: https://datatracker.ietf.org/doc/html/rfc7807
- 후속 RFC (obsolete 시킴): RFC 9457 (Problem Details for HTTP APIs — 2023 revision)
- Media type:
application/problem+json,application/problem+xml - 아카이브 URL: (미수집)
- 저자 / 조직: IETF (Editors: M. Nottingham, E. Wilde)
- 발행일: RFC 7807 — March 2016
- 마지막 확인일: 2026-05-27 (WebFetch 재검증 성공 — 5개 quote 모두 verbatim 일치. strength
needs-confirmation→official-standard으로 upgrade. [2026-05-25 capture] verbatim 보존본 유지)
핵심 인용 / Key quotes (verbatim)
[§3.1, captured 2026-05-22] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type."
[§3.1, captured 2026-05-22] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI."
[§3.2 — Extension Members, captured 2026-05-22] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize."
[§3.1 — status, captured 2026-05-22] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly."
[§3.1 — detail, captured 2026-05-22] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information."
[2026-05-27 verified — WebFetch 재검증 성공]: 본 5개 quote (RFC7807-C1 ~ C5) 모두 https://datatracker.ietf.org/doc/html/rfc7807 live 페이지에서 FOUND VERBATIM. §번호 확인: C1 = §3, C2/C4/C5 = §3.1, C3 = §3.2. strength
needs-confirmation→official-standard(IETF RFC) 으로 upgrade. [2026-05-25 capture] verbatim 본문 유지. RFC 9457 (후속) 과의 차이는 별도 raw 작성 시 검증.
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| RFC7807-C1 | problem details 의 canonical model 은 JSON object 이며, application/problem+json media type 으로 식별 |
[§3, captured 2026-05-22 + 2026-05-27 verified verbatim] "The canonical model for problem details is a JSON object. When serialized as a JSON document, that format is identified with the 'application/problem+json' media type." | official-standard [2026-05-27 verified, IETF RFC] |
HTTP API 의 error 응답 shape | XML 응답 (application/problem+xml) 도 동등하게 정의되어 있으나 본 인용 범위 밖 |
| RFC7807-C2 | consumer 는 type string 을 problem type 의 primary identifier 로 사용해야 하며 (MUST), title 은 advisory |
[§3.1, captured 2026-05-22 + 2026-05-27 verified verbatim] "Consumers MUST use the 'type' string as the primary identifier for the problem type; the 'title' string is advisory and included only for users who are not aware of the semantics of the URI." | official-standard [2026-05-27 verified, IETF RFC] |
RFC 7807 consumer 구현 | code 같은 짧은 머신리더블 식별자가 표준에 1급 필드로 있다는 뜻은 아님 — type URI 가 식별자 역할 |
| RFC7807-C3 | problem type 정의는 추가 member 로 확장 가능 (MAY), client 는 알 수 없는 확장을 무시해야 함 (MUST) |
[§3.2 — Extension Members, captured 2026-05-22 + 2026-05-27 verified verbatim] "Problem type definitions MAY extend the problem details object with additional members... Clients consuming problem details MUST ignore any such extensions that they don't recognize." | official-standard [2026-05-27 verified, IETF RFC] |
RFC 7807 의 확장 메커니즘 (예: balance, retryable 등) |
어떤 확장 필드를 표준이 권장한다는 뜻은 아님 — code/category/retryable 모두 확장 영역 |
| RFC7807-C4 | generator 는 problem details body 의 status 필드와 실제 HTTP response 의 status code 를 동일하게 사용해야 함 (MUST) |
[§3.1 — status, captured 2026-05-22 + 2026-05-27 verified verbatim] "Generators MUST use the same status code in the actual HTTP response, to assure that generic HTTP software that does not understand this format still behaves correctly." | official-standard [2026-05-27 verified, IETF RFC] |
RFC 7807 generator 구현 | HTTP status code 의 정확한 mapping (404 vs 422 등) 은 별도 표준. 본 인용은 일치 요구만 |
| RFC7807-C5 | detail member 는 client 가 문제를 정정하는 데 도움을 주는 데 초점을 두어야 하며, debugging 정보 제공이 아닌 (ought to) |
[§3.1 — detail, captured 2026-05-22 + 2026-05-27 verified verbatim] "The 'detail' member, if present, ought to focus on helping the client correct the problem, rather than giving debugging information." | official-standard [2026-05-27 verified, IETF RFC] |
detail 필드의 의도된 용도 |
i18n / localization 표준은 별도 — detail 의 언어 정책은 본 인용 범위 밖. ought to 는 SHOULD 보다 약한 어조 |
| RFC7807-C6 | i18n / Accept-Language 기반 message localization 은 RFC 7807 표준에 명시 없음 |
(부재 자체가 claim — 2026-05-27 WebFetch 재검증 시에도 i18n / Accept-Language 관련 normative 진술 발견되지 않음) | official-standard [2026-05-27 verified — 부재 사실 확인] |
다국어 error message 정책 | RFC 7807 이 i18n 을 금지한다는 뜻 아님 — 구현자 책임 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것 (2026-05-22 capture + 2026-05-27 WebFetch verbatim 재검증):
RFC7807-C1: media typeapplication/problem+json이 정식 IANA 등록 typeRFC7807-C2:typeURI 가 primary identifier (= 짧은code필드는 표준 1급 아님)RFC7807-C3: 확장 메커니즘 + unknown extension ignore 규칙RFC7807-C4: body status 와 HTTP status 일치 의무RFC7807-C5:detail의 의도된 용도 (디버깅 정보 아님)
- 이 자료가 증명하지 않는 것:
- 성공 응답 shape (RFC 7807 은 실패 전용 — 성공/실패 비대칭)
- 짧은 머신리더블
code필드의 표준 부재 (RFC7807-C2의 함의 — 확장 필드 사용 필요) category/retryable/correlation-id같은 운영 메타데이터 (C3의 확장 영역)- i18n / Accept-Language 정책 (
C6) - 외부 client 라이브러리의 실제
application/problem+json지원 범위
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- 2026-05-27 시점 재확인 + RFC 9457 (후속) 과의 차이 검토 (특히
typeURI 의 안정성 요구사항,instanceURI 동작) - ca-tmpl 의
{success, data, error.{code,category,message,retryable,details}, meta}균일 shape 가RFC7807-C2의typeURI primary identifier 와 어떻게 충돌하는지 (customcode채택 trade-off) - Spring Boot
ProblemDetailAPI (Spring Framework 6+) 와 ca-tmpl custom envelope 의 호환성
- 2026-05-27 시점 재확인 + RFC 9457 (후속) 과의 차이 검토 (특히
ca-tmpl 함의 (내 프로젝트 해석)
본 섹션은 자료 직접 인용이 아닌 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 source-summary 로 옮겨야 함.
- 표준 vs custom 의 trade-off:
- 표준 준수도 ↑ (RFC 7807), client lock-in ↓. 단
application/problem+jsoncontent negotiation 처리 client 가 드뭄 → 실질 호환성은 custom 과 큰 차이 없음 (해석). - 성공/실패 shape 비대칭 (실패 전용) vs ca-tmpl 균일 shape (
success: false분기) — DX 트레이드오프. typeURI 카탈로그 운영 부담 vs customcodeenum 단순성.
- 표준 준수도 ↑ (RFC 7807), client lock-in ↓. 단
- 운영 메타데이터:
category/retryable/code모두 RFC 7807 확장 영역 (RFC7807-C3). custom envelope 으로 1급 필드 승격하는 것이 ca-tmpl 결정. - 상태 코드 정합: ca-tmpl 도
RFC7807-C4와 동일하게 HTTP status code 와 body 상태 일치 의무 (직접적 표준 인용은 아니지만 동일 원칙).
응답 shape 예시 (RFC 7807)
{
"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"
}
- 모든 필드 optional.
type미지정 시"about:blank". - 확장: top-level 에 임의 필드 추가 가능 (예:
balance,accounts) —RFC7807-C3.
메모 / Notes
- 재검증 완료: 2026-05-27 datatracker WebFetch 재검증 성공 (5/5 verbatim, §번호 확인 — C1=§3, C2/C4/C5=§3.1, C3=§3.2).
- RFC 9457 후속: 7807 은 obsolete. wiki 승급 시 9457 기준으로 업데이트할지 결정 필요.
- 단점 (해석): i18n 미지원, code 필드 없음 (확장 영역), 성공 응답 별도 — custom envelope 대비 운영 부담 큼.
Related / 관련
- 같은 주제 다른 raw / 표준:
- RFC 9457 (Problem Details — 2023 revision) — 별도 raw 작성 후보
- Spring
ProblemDetailAPI (Spring Framework 6+) — 별도 raw 작성 후보
- 인용하는 branch:
- 인용하는 project:
- 인용한 wiki 요약: (미작성)