api-error-contract

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. 기존 코드와의 갭 분석

   • 현재 구현과 목표 계약 차이점 정리
   • 영향도 및 마이그레이션 우선순위 정의
   • 단계별 전환 전략 수립

출력 포맷

## 에러 계약(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 에러 구조

{
  "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 상태 코드 판단 기준과 클라이언트 대응 가이드가 포함되어 있어야 한다.  
구현 작업은 사용자 지시를 기다린다.