---
name: api-error-contract
description: API 에러 코드 체계와 에러 응답 계약(Contract)을 설계한다. 일관된 에러 핸들링 규칙을 정의한다.
argument-hint: "[API 코드베이스|에러 명세 문서|대상 디렉토리] (선택: 중점 에러 유형)"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Grep, Glob
---

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

## 목적

API의 에러 코드 체계와 에러 응답 계약(Contract)을 설계한다.  
현재 코드베이스의 에러 핸들링을 분석하여 불일치 지점을 식별하고, 클라이언트가 기계적으로 처리할 수 있는 일관된 에러 응답 스펙을 정의한다.  
RFC 7807(Problem Details for HTTP APIs)을 참고하여 운영, 디버깅, 클라이언트 구현 모두에 적합한 에러 체계를 구축한다.

## 입력

- API 코드베이스 디렉토리 또는 에러 처리 관련 파일 (필수)
- 기존 에러 명세 문서 (선택)
- 중점 설계 대상 에러 유형 (선택: Validation, Auth, Business 등)
- 사용 프레임워크 정보 (선택)
- 정보가 부족하면 사용자에게 질의할 것

## 절차

1. **현행 에러 핸들링 분석**
   - Grep으로 에러 반환 지점 탐색 (`res.status`, `throw`, `HttpException`, `raise`, `abort` 등)
   - 응답 포맷 패턴 수집 및 유형화
   - HTTP 상태 코드 사용 불일치 확인 (예: 400 vs 422 혼용)
   - 다국어(i18n) 메시지 처리 여부 확인
   - 에러 로그와 응답 간 trace 연계 방식 확인

2. **에러 분류 체계 설계**
   - 대분류: 4xx(Client Error), 5xx(Server Error)
   - 중분류:
     - VALIDATION
     - AUTHENTICATION
     - AUTHORIZATION
     - RESOURCE
     - BUSINESS
     - RATE_LIMIT
     - SYSTEM
   - 코드 포맷: `{CATEGORY}_{3DIGIT}` (예: AUTH_001)
   - 확장성을 고려해 번호 대역 사전 확보

3. **에러 응답 구조 정의**
   - 공통 스키마 설계
   - 필수 필드: code, message, status
   - 선택 필드: details, trace_id, doc_url
   - Validation 에러는 필드 단위 배열 포함
   - 복수 에러 반환 정책 정의

4. **HTTP 상태 코드 매핑 규칙 정의**
   - 분류별 매핑 표 작성
   - 혼동 구간 기준 명확화:
     - 400 vs 422
     - 401 vs 403
     - 404 vs 410
     - 409 vs 422
   - 500/502/503/504 구분 기준 정의

5. **클라이언트 대응 가이드 설계**
   - 에러 코드별 권장 액션 정의
   - Retry 가능 여부 명확화
   - `Retry-After` 정책 정의
   - 사용자 노출 메시지 vs 내부 메시지 구분

6. **기존 코드와의 갭 분석**
   - 현재 구현과 목표 계약 차이점 정리
   - 영향도 및 마이그레이션 우선순위 정의
   - 단계별 전환 전략 수립

## 출력 포맷

```markdown
## 에러 계약(Contract) 설계서

### 설계 원칙
- **준수 표준**: RFC 7807 기반 확장형 구조
- **코드 체계**: `{CATEGORY}_{3DIGIT}` 형식
- **국제화 전략**: code는 기계 처리 기준, message는 사용자 참조용
- **보안 원칙**: 내부 스택/DB 정보 노출 금지

### 공통 에러 응답 구조

```json
{
  "error": {
    "code": "VALIDATION_001",
    "message": "입력값이 올바르지 않습니다.",
    "status": 400,
    "details": [],
    "trace_id": "trace-abc-123",
    "doc_url": "https://api.example.com/docs/errors/VALIDATION_001"
  }
}
```

### Validation 에러 구조

```json
{
  "error": {
    "code": "VALIDATION_001",
    "message": "입력 데이터 검증 실패",
    "status": 422,
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "이메일 형식이 올바르지 않습니다."
      }
    ]
  }
}
```

### 에러 코드 목록

| 코드             | HTTP | 분류             | 설명     | Retry 가능 | 클라이언트 권장 액션    |
| -------------- | ---- | -------------- | ------ | -------- | -------------- |
| AUTH_001       | 401  | AUTHENTICATION | 토큰 만료  | Yes      | 토큰 재발급         |
| AUTH_002       | 401  | AUTHENTICATION | 토큰 무효  | No       | 재로그인           |
| AUTH_003       | 403  | AUTHORIZATION  | 권한 부족  | No       | 권한 요청          |
| VALIDATION_001 | 422  | VALIDATION     | 입력값 오류 | No       | 필드 수정          |
| RESOURCE_001   | 404  | RESOURCE       | 리소스 없음 | No       | ID 확인          |
| RATE_001       | 429  | RATE_LIMIT     | 요청 초과  | Yes      | Retry-After 대기 |
| SYSTEM_001     | 500  | SYSTEM         | 내부 오류  | Yes      | 일정 시간 후 재시도    |

### HTTP 상태 코드 판단 기준

| 상황             | 상태 코드 | 판단 기준     |
| -------------- | ----- | --------- |
| JSON 파싱 실패     | 400   | 문법 오류     |
| 필수값 누락         | 422   | 의미적 검증 실패 |
| 인증 정보 없음       | 401   | 인증 실패     |
| 인증은 되었으나 권한 없음 | 403   | 인가 실패     |
| 이미 삭제된 리소스     | 410   | 영구 제거됨    |
| 동시성 충돌         | 409   | 상태 충돌     |

### 클라이언트 에러 처리 가이드
| 분류             | 기본 전략    | 사용자 메시지 노출 | 재시도 |
| -------------- | -------- | ---------- | --- |
| VALIDATION     | 즉시 수정    | 가능         | 불가  |
| AUTHENTICATION | 토큰 갱신    | 제한적        | 조건부 |
| AUTHORIZATION  | 권한 안내    | 가능         | 불가  |
| RATE_LIMIT     | 대기 후 재시도 | 제한적        | 가능  |
| SYSTEM         | 자동 재시도   | 노출 금지      | 가능  |

### 기존 코드와의 갭 분석

| 위치          | 현재 방식      | 목표 방식          | 영향도    | 우선순위 |
| ----------- | ---------- | -------------- | ------ | ---- |
| [file:line] | 단순 문자열 반환  | 표준 error 객체 반환 | High   | P1   |
| [file:line] | 400/422 혼용 | 명확한 구분 적용      | Medium | P2   |

### 마이그레이션 로드맵

1. **Phase 1**: [공통 글로벌 에러 핸들러 도입]
2. **Phase 2**: [주요 엔드포인트부터 표준 구조 적용]
3. **Phase 3**: [SDK 및 문서 업데이트]
4. **Phase 4**: [레거시 포맷 제거]
```

## 안전 유의사항

- 에러 응답에 스택트레이스·DB 정보 노출 금지
- 보안 관련 에러는 과도한 상세 메시지 제공 금지
- 설계만 수행하며 코드 수정은 하지 않는다
- 응답 포맷 변경이 기존 클라이언트에 영향을 주는 경우 Breaking Change로 명시한다

---

## 종료 조건

위 포맷에 따른 에러 계약 설계서를 작성하면 종료한다.  
에러 코드 체계가 분류 기준에 따라 정의되어 있고, HTTP 상태 코드 판단 기준과 클라이언트 대응 가이드가 포함되어 있어야 한다.  
구현 작업은 사용자 지시를 기다린다.