# 요청 오류 계약

요청 파싱, 검증, 예외 매핑, 오류 봉투, 클라이언트에 보이는 실패 동작에 이 참고 자료를 사용합니다.

## 목록화

- 진입 표면: 라우트, RPC 메서드, 웹훅 엔드포인트, 폼 전송, 명령줄 명령, 일괄 가져오기.
- 입력 계약: 경로/쿼리/본문/헤더 필드, 업로드 파일, 콘텐츠 형식, 스키마 버전, 기본값, 강제 변환, 알 수 없는 필드 처리.
- 검증 소유자: 프레임워크 검증기, 스키마 라이브러리, DTO 클래스, 미들웨어, 서비스 보호 로직, 데이터베이스 제약, 외부 제공자 응답.
- 오류 매퍼: 예외 필터, 미들웨어, 전역 처리기, 라우트 로컬 도우미, 도메인 오류 변환기, 역방향 프록시.
- 소비자: 브라우저 UI, 모바일 앱, SDK, 파트너 연동, 일괄 가져오기, 모니터링 규칙, 생성된 클라이언트.

## 오류 분류

| 실패 경로 | 검토 초점 |
| --- | --- |
| 파싱 실패 | 잘못된 JSON/폼/멀티파트, 콘텐츠 형식, 본문 크기, 업로드 제한 |
| 검증 실패 | 필드 경로, 메시지, 다국어 키, 오류 코드, 기본값과 강제 변환 |
| 권한 실패 | 인증 필요, 권한 범위 거부, 테넌트/객체 접근, 존재 여부 유출 방지 |
| 업무 규칙 실패 | 도메인 코드, 충돌 설명, 사용자 행동, 재시도 가능성 |
| 찾을 수 없음/충돌 | 안정적인 상태 코드, 객체 가시성, 멱등성, 클라이언트 캐시 동작 |
| 호출 제한/할당량 | 재시도 시점, 제한 기준, 사용자에게 안전한 설명, 관측성 |
| 예상하지 못한 오류 | 정리된 본문, 상관관계 ID, 로그/추적 상세, 알림 |

## 계약 규칙

- 소비자를 확인하지 않고 오류 봉투 형태, 상태 코드, 기계가 읽는 코드, 필드 경로 이름을 바꾸지 않습니다.
- 사람이 읽는 메시지를 파싱하게 만들기보다 안정적인 기계용 코드를 선호합니다.
- 사용자 메시지는 비밀, 객체 존재 여부, 내부 경로, SQL, 스택 추적, 토큰, 제공자 페이로드를 유출하지 않을 만큼 일반적으로 유지합니다.
- 검증은 요청 경계 가까이에 두되, 도메인 불변식을 컨트롤러와 서비스에 서로 다르게 중복하지 않습니다.
- 데이터베이스 제약이 실제 불변식을 보장한다면 해당 실패를 사전 검증과 같은 클라이언트 계약으로 매핑합니다.
- 버전이 있는 API에서는 오류 계약이 이전 버전, 새 버전, 호환 어댑터 중 어디에 속하는지 결정합니다.

## 검증

- 성공과 대표 실패 경로에 대한 계약 테스트 또는 스냅샷 테스트.
- UI 폼 매핑, SDK 오류 처리, 재시도 동작, 생성된 클라이언트에 대한 소비자 테스트.
- 존재 여부 유출, 자세한 스택 추적, 반사된 입력, 로그의 민감 값에 대한 보안 점검.
- 상관관계 ID, 라우트, 오류 코드, 정리된 검증 요약, 알림 심각도에 대한 관측성 점검.
- 기존 클라이언트가 새 코드나 필드 경로를 받을 수 있으면 이전 메모.
