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 등)
사용 프레임워크 정보 (선택)
정보가 부족하면 사용자에게 질의할 것

절차

현행 에러 핸들링 분석
- Grep으로 에러 반환 지점 탐색 (res.status, throw, HttpException, raise, abort 등)
- 응답 포맷 패턴 수집 및 유형화
- HTTP 상태 코드 사용 불일치 확인 (예: 400 vs 422 혼용)
- 다국어(i18n) 메시지 처리 여부 확인
- 에러 로그와 응답 간 trace 연계 방식 확인
에러 분류 체계 설계
- 대분류: 4xx(Client Error), 5xx(Server Error)
- 중분류:
  - VALIDATION
  - AUTHENTICATION
  - AUTHORIZATION
  - RESOURCE
  - BUSINESS
  - RATE_LIMIT
  - SYSTEM
- 코드 포맷: {CATEGORY}_{3DIGIT} (예: AUTH_001)
- 확장성을 고려해 번호 대역 사전 확보
에러 응답 구조 정의
- 공통 스키마 설계
- 필수 필드: code, message, status
- 선택 필드: details, trace_id, doc_url
- Validation 에러는 필드 단위 배열 포함
- 복수 에러 반환 정책 정의
HTTP 상태 코드 매핑 규칙 정의
- 분류별 매핑 표 작성
- 혼동 구간 기준 명확화:
  - 400 vs 422
  - 401 vs 403
  - 404 vs 410
  - 409 vs 422
- 500/502/503/504 구분 기준 정의
클라이언트 대응 가이드 설계
- 에러 코드별 권장 액션 정의
- Retry 가능 여부 명확화
- Retry-After 정책 정의
- 사용자 노출 메시지 vs 내부 메시지 구분
기존 코드와의 갭 분석
- 현재 구현과 목표 계약 차이점 정리
- 영향도 및 마이그레이션 우선순위 정의
- 단계별 전환 전략 수립

출력 포맷

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

마이그레이션 로드맵

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


## 안전 유의사항

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

---

## 종료 조건

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

Más de este repositorio

mismo repositorio

api-auth-review

gaebalai/claude-code-kit-ko

API 인증/인가(Authorization) 설계를 리뷰하고, 권한 체크 누락·스코프 설계 미흡·권한 상승 리스크를 탐지한다. 접근 통제의 안전성을 검증한다.

2026-02-252

api-client-sdk-notes

gaebalai/claude-code-kit-ko

API 이용자를 위한 SDK 릴리스 노트 및 마이그레이션 가이드를 생성한다. 변경 사항을 클라이언트 관점에서 정리하고, 구체적인 전환 절차를 제공한다.

2026-02-252

api-endpoint-design

gaebalai/claude-code-kit-ko

요구사항으로부터 RESTful API 엔드포인트를 설계한다. 네이밍 규칙, 리소스 단위, 에러 처리, 응답 구조를 일관되게 정의한다.

2026-02-252

api-openapi-diff

gaebalai/claude-code-kit-ko

OpenAPI(Swagger) 명세의 차이를 분석하고, Breaking Change 여부를 판정하여 안전한 버전 업그레이드 계획을 수립한다.

2026-02-252

api-pagination-standard

gaebalai/claude-code-kit-ko

API 리스트 엔드포인트의 페이지네이션·필터링·정렬 구현을 분석하고, 통일된 표준 규격을 수립한다.

2026-02-252

api-versioning-plan

gaebalai/claude-code-kit-ko

API 메이저 버전 전환(v1 → v2)을 위한 단계적 마이그레이션 계획을 수립한다.

2026-02-252

## 에러 계약(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" } }

{ "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

토큰 무효

재로그인

AUTH_003

403

AUTHORIZATION

권한 부족

권한 요청

VALIDATION_001

422

VALIDATION

입력값 오류

필드 수정

RESOURCE_001

404

RESOURCE

리소스 없음

ID 확인

RATE_001

429

RATE_LIMIT

요청 초과

Yes

Retry-After 대기

SYSTEM_001

500

SYSTEM

내부 오류

Yes

일정 시간 후 재시도

상황

상태 코드

판단 기준

JSON 파싱 실패

400

문법 오류

필수값 누락

422

의미적 검증 실패

인증 정보 없음

401

인증 실패

인증은 되었으나 권한 없음

403

인가 실패

이미 삭제된 리소스

410

영구 제거됨

동시성 충돌

409

상태 충돌

분류

기본 전략

사용자 메시지 노출

재시도

VALIDATION

즉시 수정

가능

불가

AUTHENTICATION

토큰 갱신

제한적

조건부

AUTHORIZATION

권한 안내

가능

불가

RATE_LIMIT

대기 후 재시도

제한적

가능

SYSTEM

자동 재시도

노출 금지

가능

위치

현재 방식

목표 방식

영향도

우선순위

[file:line]

단순 문자열 반환

표준 error 객체 반환

High

[file:line]

400/422 혼용

명확한 구분 적용

Medium

## 안전 유의사항 - 에러 응답에 스택트레이스·DB 정보 노출 금지 - 보안 관련 에러는 과도한 상세 메시지 제공 금지 - 설계만 수행하며 코드 수정은 하지 않는다 - 응답 포맷 변경이 기존 클라이언트에 영향을 주는 경우 Breaking Change로 명시한다 --- ## 종료 조건 위 포맷에 따른 에러 계약 설계서를 작성하면 종료한다. 에러 코드 체계가 분류 기준에 따라 정의되어 있고, HTTP 상태 코드 판단 기준과 클라이언트 대응 가이드가 포함되어 있어야 한다. 구현 작업은 사용자 지시를 기다린다.