Problem 정규화 계약

안전한 오류 정보는 공유하고 전송·복구 결정은 명시적으로 구분합니다.

공개 필드

공통 표현은 type, title, code, detail과 선택적인 traceId, instance, transport를 사용합니다. 안정적인 식별자는 urn:akkadia:problem:<encoded-code> 형식입니다. detail 문구가 아닌 code로 분류하세요.

경계	계약
HTTP	`application/problem+json`. 본문 상태는 실제 400–599 응답과 일치
소켓	기존 봉투 안의 공개 Problem. 본문에 가상의 HTTP 상태를 만들지 않음
로컬 앱	존재하지 않는 HTTP 응답 상태 없이 Problem 정보 사용
명령 결과	기존 타입 기반 결과 봉투 유지. 전역 치명 오류로 변환하지 않음

기존 소켓 봉투의 바깥쪽 상태 필드는 호환성을 위해 남을 수 있습니다. 새 소비자는 이 필드에 의존하지 않습니다. 네이티브 연결 실패는 연결 수립 과정에서 처리합니다.

안전한 직렬화

publicProblem은 안전한 기본 안내를 선택합니다. 스택, 원인, 원본 메시지, 메타데이터는 별도의 비공개 진단에 남깁니다. HTTP 로그와 응답은 같은 추적 ID를 사용하고 x-trace-id 헤더에도 전달합니다.

parseProblemDetails는 지원하는 본문과 기존 봉투를 받아 필드를 검증하고 허용된 정보만 복사합니다. readHttpProblem은 비어 있거나 HTML인 HTTP 실패 응답도 처리합니다. 외부 문구를 파싱했다고 해서 사용자 화면에 그대로 노출해도 되는 것은 아닙니다.

복구는 동작별 책임입니다

인증·세션 입장 실패나 없는 방·초기화 실패는 연결 종료가 필요할 수 있습니다. 일반 명령 거부, HTTP 4xx, 알 수 없는 코드가 자동으로 세션을 끝내지는 않습니다. 서버는 복구 불가능한 연결을 명시적으로 종료할 수 있습니다.

제작, 보상 수령, 체인 변경을 무조건 재시도하지 마세요. 영수증과 권위 있는 상태를 먼저 확인하세요. 공용 Axios 요청기는 기존 소비자 호환성을 위해 원래 Axios 오류를 계속 던지고 어댑터가 Problem 정보를 읽습니다.

호환성

AppError는 내부 예외 표현으로 유지하며 구현 내부에서는 필요한 네이티브 예외를 사용할 수 있습니다. 표시·전송 경계에서 정규화하세요. 공개 오류 계약을 바꾸면 클라이언트와 서버를 함께 배포하세요. 코드가 없는 이전 응답은 메시지 문자열 비교가 아니라 안전한 기본값으로 처리합니다.

필드 모델은 Problem Details의 형식을 따릅니다. 소켓과 앱은 그 정보 모델을 재사용할 뿐, 필드가 비슷하다는 이유로 HTTP 응답이 되지는 않습니다.

표준 참고

Problem Details for HTTP APIs (RFC 9457) 은 HTTP 오류 정보 모델을 정의하며 RFC 7807을 대체합니다. Akkadia는 code, traceId, transport 같은 앱 확장 필드를 사용합니다. 이 표준의 HTTP 의미가 소켓이나 로컬 앱 오류를 HTTP 응답으로 바꾸지는 않습니다.