API 오류 코드 및 모범 사례
1) 오류를 표준화하는 이유
고객의 예측 가능성: 단일 형식 및 레트라 동작.
가속 디버그: 'trace _ id '/' 요청 _ id', 안정적인 '오류 _ 코드'.
보안: SQL/스택 추적/구성 요소가 누출되지 않습니다.
관찰 가능성: 오류 분류 (검증, 할당량, 타임 아웃 등) 에 대한보고.
2) 기본 원칙
1. 모든 4xx/5xx (및 부분 오류가있는 2xx-별도의 체계) 에 대한 단일 응답 형식.
2. 명확한 상태: 올바른 상태가 가장 중요합니다.
3. 두 가지 수준의 코드: 전송 ('상태') 및 도메인 안정 '오류 _ 코드'.
4. 검색 가능한 대 검색 불가능: 명시 적으로 지정하고 백오프에 대한 힌트를 제공하십시오.
5. 기본 보안: 세부 정보-권한이있는 고객에게만; 내부 흔적이 없습니다.
6. 현지화: 기계 코드는 안정적으로 유지됩니다. 텍스트-번역합니다.
3) 단일 오류 형식 (RFC 7807 기반)
권장 JSON (확장 된 '응용 프로그램/문제 + json'):json
{
"type": "https://api. example. com/errors/validation_failed",
"title": "Validation failed",
"status": 422,
"error_code": "VAL_001",
"detail": "Field 'email' must be a valid address",
"instance": "req_01HZY...93",
"trace_id": "a1b2c3d4e5f6",
"retriable": false,
"errors": [
{"field": "email", "code": "email_invalid", "message": "Invalid email"}
],
"hint": "Fix payload and retry",
"meta": {"docs": "https://docs. example. com/errors#VAL_001"}
}필수: '유형', '제목', '상태', '오류 _ 코드', '추적 _ id'.
선택 사항: '오류 []' (필드 별), '검색 가능', '힌트', '메타'.
- '콘텐츠 유형: 응용 프로그램/문제 + json'
- 'X-Request-ID '/' Traceparent' (W3C)
- (429/503) '재시도 후' (초 또는 날짜)
4) 상태 시맨틱 ("클래식" 및 실습 병합)
2xx (미묘한 성공)
200 OK는 일반적인 성공입니다.
201 만들어진 위치.
202 허용 - 대기열에서 비동기 적으로 ('상태 _ 리스트' 제공).
207 다중 상태-부분 성공 (가능한 경우 피하십시오).
4xx (클라이언트 오류)
400 나쁜 요청 - 구문/형식이지만 현장 검증은 아닙니다 (바람직하게는 422).
401 무단 결제-아니오/유효하지 않은 토큰. 'WWW-Authenticate' 를합시다.
403 금지-토큰은 유효하지만 충분한 권리가 없습니다 (RBAC/ABAC/제한).
404 찾을 수 없음-리소스/엔드 포인트 없음.
409 충돌-최적의 잠금, demotency.
410 Gone-엔드 포인트가 영구적으로 제거되었습니
412 전제 조건 실패-ETag/If-Match가 실패했습니다.
415 지원되지 않는 미디어 유형 - 유효하지 않은 '콘텐츠 유형'.
422 처리 불가능한 엔티티-비즈니스 규칙 검증.
429 너무 많은 요청-할당량/속도를 초과했습니다 (§ 7 참조).
5xx (서버 오류)
500 내부 서버 오류 - 갑작스런 오류; 세부 사항을 공개하지 않습니다.
502 나쁜 게이트웨이-업스트림 오류.
503 서비스 사용할 수 없음-저하/과부하, '재생 후' 제공.
504 게이트웨이 시간 초과 - 백엔드 시간 초과.
5) 도메인 분류법 '오류 _ 코드'
다음 범위를 권장합니다
'λH _' - 인증/인증.
'VAL _' - 입력 데이터 검증.
'RATELIMIT _' -할당량과 속도.
'IDEMP _' - demempotence/complex입니다.
'CONFLICT _' - 버전/상태.
'DEP _' - 종속성 (PSP/디렉토리/시스템).
'PAY _' - 결제 도메인의 비즈니스 오류.
'SEC _' - 보안 (서명, HMAC, mTLS).
'INT _' -내부 갑작스런.
- 시간이 지남에 따라 안정성 (back-compat).
- 오류 디렉토리의 설명 및 예 (문서 + 기계 판독 가능 JSON).
6) 검색 가능 vs 검색 불가능
필드:- '검색 가능: 진정한' 거짓 '
- '참' - 반드시 '재시도 후' (초 단위) 또는 계약 "지수 백오프 (1-2 초부터 시작, 최대 30-60 초)" 인 경우.
일반적으로 '502/503/504', 일부 '500', '429' (창 뒤).
검색 할 수 없음: '400/401/403/404/409/410/415/422'.
7) 요율 제한 및 할당량 오류 (429)
몸:json
{
"type": "https://api. example. com/errors/rate_limited",
"title": "Rate limit exceeded",
"status": 429,
"error_code": "RATELIMIT_RPS",
"detail": "Too many requests",
"retriable": true
}- '재생 후: 12'
- 'X-RateLimit-Limit', 'X-RateLimit-Remaining', 'X-RateLimit-Reset'
- 차이나: 'X-Quota-Limit', 'X-Quota-Remaining', 'X-Quota-Reset'
8) 이념과 갈등
쓰기 요청- 'Idempotency-Key' (24-72 시간 내에 고유).
충돌 시작 → 409 '오류 _ 코드와의 충돌: "IDEMP _ REPLAY"'.
ETag → 412 전제 조건에 대한 리소스 버전 충돌 실패.
응답에서 안전한 재 요청을 위해 'resource _ id '/' resource _ url을 첨부하십시오.
9) 검증 및 422
현장별 오류 목록을 반환합니다:json
{
"status": 422,
"error_code": "VAL_001",
"errors": [
{"field":"email","code":"email_invalid","message":"Invalid email"},
{"field":"age","code":"min","message":"Must be >= 18"}
]
}- 비즈니스 검증을 위해 선호되는 400-422에서 동일하게 복제하지 마십시오.
- 메시지는 사람이 읽을 수 있습니다 '코드' 는 기계로 읽을 수 있습니다.
10) 보안 오류
절대: 추적, SQL, 파일 경로, 개인 호스트 이름 스택.
PII 편집; GDPR/DSAR을 주시하십시오.
서명/HMAC의 경우 'SEC _ SIGNATURE _ MISMATCH' (403) 와 'SEC _ TIMESTAMP _ SKEW' (401/403) 를 "시간 5 분 확인" 이라는 프롬프트로 구분하십시오.
11) 상관 및 관찰 가능성
항상 'trace _ id '/' X-Request-ID' 를 추가하고 로그/트랙을 스크롤하십시오.
'오류 _ 코드' 및 '상태' → 대시 보드 "상단 오류", "새로운 대 알려진" 으로 오류를 집계하십시오.
경고: 5xx/422/429 스파이크, p95 대기 시간, 오류 공유.
12) gRPC/GraphQL/웹 후크-매핑
gRPC 을 사용합니다
그래프 QL
전송 200이지만 내부의 '오류 []' -추가 '확장. 코드 '겠습니다' trace _ id '.
"치명적" (인증/할당량) 의 경우-실제 TH 401/403/429가 더 좋습니다.
웹 후크
2xx 수신자 만 성공하는 것을 고려하십시
기하 급수적 인 백오프, 'X-Webhook-ID', 'X-Signature' 가있는 Retrai.
수신자로부터 410-리트레이 중지 (엔드 포인트 제거).
13) 오류 발생
'유형 '/' 오류 _ 코드' - 안정; 새로운-추가 만.
바디 스키마를 변경할 때 사소한 버전의 API 또는 '문제 + json을 올리십시오. v = 2 '.
문서: 코드 테이블 + 예; 변경 로그 오류.
14) 문서 (OpenAPI 단편)
글로벌 응답
yaml components:
responses:
Problem:
description: Problem Details content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
schemas:
Problem:
type: object required: [type, title, status, error_code, trace_id]
properties:
type: { type: string, format: uri }
title: { type: string }
status: { type: integer }
error_code: { type: string }
detail: { type: string }
instance: { type: string }
trace_id: { type: string }
retriable: { type: boolean }
errors:
type: array items:
type: object properties:
field: { type: string }
code: { type: string }
message: { type: string }엔드 포인트의 예
yaml paths:
/v1/users:
post:
responses:
'201': { description: Created }
'401': { $ref: '#/components/responses/Problem' }
'422': { $ref: '#/components/responses/Problem' }
'429': { $ref: '#/components/responses/Problem' }
'500': { $ref: '#/components/responses/Problem' }15) 테스트 및 품질
테스트 계약: '응용/문제 + json', 필요한 필드와 일치합니다.
부정적인 테스트: 모든 지점 401/403/404/409/422/429/500.
혼돈/대기 시간: 5xx/503/504/429 ('Redch-After') 에 대한 리트레이 확인.
보안 테스트: 내부 메시지 없음, 올바른 PII 마스크.
후진: 오래된 고객은 새로운 분야를 이해합니다 (추가, 중단하지 마십시오).
16) 구현 점검표
- 단일 '문제 + json' + 안정적인 '오류 _ 코드'.
- 올바른 도/gRPC/그래프 QL 의미론.
- 검색 가능/검색 불가능 + '재시도 후 '/백오프 권장 사항.
- 속도 제한 헤더 및 429 동작.
- 이념성 ('Idempotency-Key', 409/412).
- 보안: 스택 추적/비밀, PII 에디션이 없습니다.
- 모든 오류에서 'trace _ id '/' X-Request-ID'
- 오류 카탈로그 문서 및 예.
- 오류 분류법에 의한 모니터링.
- 부정적인 시나리오의 자동 테스트.
17) 미니 -FAQ
400은 422와 어떻게 다릅니 까?
400 - 요청 중단 (구문/내용 유형). 422-구문에서는 유효하지만 비즈니스 규칙이 통과되지 않았습니다.
401은 언제이고 403은 언제입니까?
401 - 아니오/잘못된 토큰; 403-토큰이 있고 권리가 충분하지 않습니다.
'재시도 후' 가 항상 필요합니까?
429/503의 경우 그렇습니다. 나머지는 검색 가능합니다. 명시적인 권장 사항을 제시하는 것이 좋습니다.
합계
잘 설계된 버그는 올바른 TP 상태, 단일 '문제 + json', 안정적인 '오류 _ 코드', 명시 적 재 트레이 힌트 및 강력한 보안 계약입니다. 형식을 표준화하고 분류법을 문서화하며 원격 측정 및 테스트를 추가하면 API가 예측 가능하고 안전하며 통합 친화적입니다.