모든 클라이언트에 표시되는 API 실패에 대해 기계 판독 가능한 RFC 9457 문제 응답을 제공하며, 안정적인 타입 URI, 상관 관계를 위한 확장 필드, 내부 상태 누출이나 재시도 의미 체계 우회를 방지하는 카탈로그를 포함합니다.
패키지 상태: AI 지원 참조 패키지. 정적 패키지 검증을 통과했으며, 구현 시나리오는 아직 실행되지 않았고 안정적인 도입 전에는 인간 도메인 검토가 필요합니다.
결정 사항
클라이언트가 관찰할 수 있는 모든 HTTP API 오류는 RFC 9457에 맞춘 단일 문제 세부 정보 객체를 반환합니다. 사람이 읽을 수 있는 상세 정보는 부차적이며, error-catalog.yaml의 항목에서 {catalog_uri_base}/{uri_suffix}로 구성된 안정적인 type URI가 우선합니다. 내부 예외 클래스, 스택 추적, 데이터베이스 식별자는 클라이언트 페이로드에 절대 나타나지 않습니다. 재시도 가능한 실패는 기계 판독 가능한 확장 필드를 노출하여 일반 클라이언트가 산문을 파싱하지 않고도 속도 제한과 멱등성을 준수할 수 있게 합니다.
범위
- 외부 통합자가 볼 수 있는 4xx 및 5xx 결과에 대한 동기 REST 및 RPC 스타일 HTTP 응답.
- 문제 유형 레지스트리, 확장 필드 어휘, 상관 관계 식별자, 검증 오류 배열 스키마.
- 제품이 의도적으로 노출하는 범위를 넘어서는 권한 구분 누출 없이 도메인 실패를 카탈로그 항목에 매핑.
이 범위 외
- 별도의 스키마를 사용하는 GraphQL 오류 확장(동일 카탈로그 URI를 참조할 수 있으나 여기서는 명세하지 않음).
- WebSocket 종료 코드 또는 gRPC 상태 세부 정보와 같은 비 HTTP 전송.
- API 통합자와 관련 없는 최종 사용자 마케팅 문구 현지화.
계약
- 모든 클라이언트에 표시되는 오류 응답은
Content-Type: application/problem+json을 포함하며, 본문에는 RFC 9457에 따라 HTTP 상태 코드와 일치하는 최소한의type,title,status가 포함됩니다. type값은 카탈로그 항목에 대해{catalog_uri_base}/{uri_suffix}와 같으며, 알려지지 않은 타입은 비개발 환경에서 응답 필터에 의해 거부됩니다.- 확장 필드
correlation_id는 이 프로필의 모든 클라이언트에 표시되는 오류(모든 4xx 및 5xx)에 필수이며, 서버 로그 및X-Request-Id헤더에 기록된 값과 일치합니다(헤더가 있을 경우). - 카탈로그 항목별로
error-catalog.yaml의required_extensions및optional_extensions가 적용되며, 필수 확장이 누락되면 응답 필터가 실패합니다. - 검증 실패는
validation타입을 사용하며 필수errors배열을 포함합니다; 각 요소는errors_array_schema에 따라field및sub_type을 포함하며, 원시 데이터베이스 제약 조건 이름은 포함하지 않습니다. - HTTP 502 및 503에 대한 카탈로그 타입은 각각
bad-gateway및service-unavailable이며, 둘 다retryable: true및retry_after_seconds가 필요합니다. - 클라이언트 및 게이트웨이는
unknown_extension_behavior가ignore일 때 알려지지 않은 확장 필드를 무시해야 하며, 이를 오류로 처리해서는 안 됩니다. - 권한 실패는 제품 정책이 균일한 404/403 동작을 요구할 때 리소스 존재 여부를 노출하지 않는 카탈로그 타입을 반환합니다.
- 내부 전용 진단 정보는 서버 측에 저장되며 외부 호출자를 위한 문제
detail필드에 절대 복사되지 않습니다.
구현 지침
- 서비스 경계별로 문제 생성 모듈을 중앙 집중화하여 컨트롤러가 임의 JSON 오류 형식을 생성하지 못하게 합니다.
- 코드가 참조하기 전에 카탈로그에 새 타입을 등록하며, 레지스트리에 없는 타입을 코드에서 언급하면 CI가 실패합니다.
- 모든 클라이언트에 표시되는 결과에 대해 가장자리에서 상관 관계 식별자를 바인딩하고 하위 호출로 전파합니다.
- 운영자 런북에 타입 URI 구성을 기본 URI와 접미사로 문서화하며, 각 서비스에서 임의 문자열 결합을 하지 않습니다.
실패 처리 및 보호 조치
- 문제 직렬화 실패 시 빈 본문이나 HTML 오류 페이지 대신 상관 관계 ID가 포함된 카탈로그 타입
internal을 반환합니다. - 상위 종속성이 시간 초과되면 작업이 안전하게 재시도 가능할 때
service-unavailable타입과 재시도 확장을 포함한 503을 발행합니다. - 속도 제한 응답에는 인증된 호출자가 이미 알고 있는 것 외에 테넌트 식별 세부 정보를 확장 필드에 포함해서는 안 됩니다.
- 카탈로그 마이그레이션 중에는 프로필 폐기 기간이 만료될 때까지 폐기된 타입 URI에 대한 별칭 접미사 항목을 유지합니다.
검증 및 운영
- 계약 테스트는 Content-Type, 4xx 및 5xx의 correlation_id, 카탈로그 멤버십, 타입별 필수 확장을 검증합니다.
- 알려지지 않은 타입 필터 거부를 모니터링하며, 급증은 배포되지 않은 카탈로그 업데이트 또는 무단 서비스가 있음을 나타냅니다.
- 매월 프로덕션 5xx 문제 샘플링을 통해
detail에 스택 조각이 나타나지 않는지 확인합니다.
도입 가정
example.yaml및error-catalog.yaml의 이름과 숫자 값은 도입 프로필이며 보편적 기본값이 아닙니다.- 도입 팀은 카탈로그 URI 네임스페이스, 상관 관계 ID 형식, 도메인 예외에서 문제 타입으로의 매핑을 소유합니다.