오류 처리 및 상태 코드

1) 오류를 표준화하는 이유

• 문제 유형을 예측할 수 있습니다
• 클라이언트에게 유효한 프롬프트를 제공합니다 (다음에해야 할 일)
• 내부 부품의 누출을 방지하고
• retras 및 demempotency와 호환됩니다.

2) 디자인 원칙

1. 모든 서비스에 대한 하나의 오류 체계 (REST/GraphQL/gRPC/webhooks).
2. 배신의 명확한 의미론: 어떤 코드가 후퇴하는지, 그렇지 않은지.
3. 쓰기 작업에 실패했습니다. 조용한 불일치보다 4xx/5xx가 더 좋습니다.
4. 누출 없음: SQL, 스택, 구성 요소, 내부 ID를 공개하지 마십시오.
5. 추적-항상 'trace _ id '/' correlation _ id' 를 반환합니다.
6. 메시지의 현지화는 선택 사항이지만 코드 및 '이유' 는 안정적으로 유지됩니다.

3) 단일 형식 (문제 정보/JSON)

json
{
"type": "https://errors.example.com/auth/invalid-token",
"title": "Invalid access token",
"status": 401,
"code": "AUTH_INVALID_TOKEN",
"detail": "Token expired or signature invalid.",
"instance": "/api/v1/payments/12345",
"trace_id": "01HX3...ABC",
"hint": "Obtain a new token via OAuth2 refresh.",
"meta": {
"scope": "payments:write",
"policy": "deny-by-default"
}
}

• '유형' 은 안정적인 오류 클래스 DM입니다.
• '코드' - 짧은 도메인 머신 코드 (릴리스 간 안정).
• '힌트' -클라이언트를 위해해야 할 일 (반복, 토큰 업데이트, 매개 변수 변경).
• '메타' -보안 부품 (비밀 및 PII 없음).

4) 상태 코드 맵 (최소 세트)

인증/인증

400 나쁜 요청-구조적 검증/체계.
401 무단 결제-아니오/유효하지 않은 토큰. 'WWW-washer' 를 추가하십시오.
403 금지-인증되었지만 권리/정책은 거부되지 않았습니다.
404 발견되지 않음-권한이없는 리소스의 존재를 가리십시오.
409 충돌-버전/상태 충돌 (낙관적 잠금, demempotency).
451 법적 이유로 사용할 수 없음-준수/관할 블록.

한계 및 보호

408 요청 시간 초과-클라이언트가 본문을 너무 느리게 보냅니다.
409/425 너무 일찍-0-RTT/SL 1의 조기 반복 금지. 3.
429 너무 많은 요청-' 재시도 후 '및 제한 정책.
499 클라이언트 폐쇄 요청- (주변/NGINX에서) 클라이언트가 연결을 끊었습니다.

데이터 및 비즈니스 규칙

422 처리 불가능한 콘텐츠-비즈니스 검증이이 체계를 통과했지만 의미는 잘못되었습니다.
423 잠금-리소스 차단 (KYC 검토, AML 동결).
409 충돌 - 이중 제출, 인종, 상태 제한 (예: "이미 진행 중").
410 Gone-엔드 포인트/리소스 삭제 (완료 완료).

서버

500 내부 서버 오류 - 알 수 없는 오류; 세부 사항을 공개하지 않습니

502 나쁜 게이트웨이-종속성으로 오류/설명이 반환되었습니다.
503 서비스 사용할 수 없음-저하/계획된 작업; '재생 후' 를 추가하십시오.
504 게이트웨이 시간 초과.

5) 재 트레이 및 demopotency 의미론

400/401/403/404/422를 철회 할 수 없습니다 (고객이 요청을 변경하지 않는 한).
철회: 408/429/5xx/425/499/504 (백오프 + 지터 포함).
Idempotency: 'POST' 의 경우 'Idempotency-Key' (UUIDv4) 를 활성화하십시오.

재 시도 충돌의 경우 '힌트:' 동일한 Idempotency-Key 또는 GET 상태 사용 '으로 409를 반환하십시오.
추가 'Idempotency-Replay: 참' 저장된 결과를 반환 할 때.

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 1730641030

6) 입력 검증: 필드 오류 구조

400/422의 경우 일련의 필드 오류를 사용하십시오

json
{
"type": "https://errors.example.com/validation",
"title": "Validation failed",
"status": 422,
"code": "VALIDATION_ERROR",
"trace_id": "01HX4...XYZ",
"errors": [
{"field": "amount", "rule": "min", "message": "Must be >= 10"},
{"field": "currency", "rule": "enum", "message": "Unsupported currency"}
]
}

7) 부분 오류 (배치/부분 오류)

배치 끝점에서 구조없이 200 내부의 오류를 숨기지 마십시오. 각 작업마다 고유 한 상태를 갖는 다양한 결과 배열로 207 다중 상태 또는 200을 반환하십시오

json
{
"status": "partial",
"succeeded": 8,
"failed": 2,
"results": [
{"id": "op1", "status": 201},
{"id": "op2", "status": 422, "error": {"code":"VALIDATION_ERROR","detail":"..."}}
]
}

8) 페이지와 "빈" 답변

빈 컬렉션-200 '항목: [], 404가 아님.

(PHP 3 = 3.0.6, PHP 4)

잘못된 토큰-400 코드: PAGINATION _ CURSOR _ INVALID '.

9) 웹 후크: 신뢰할 수있는 배달

이벤트 (HMAC) 에 서명하고 처리 전에 확인하십시오.
성공적인 처리에 대한 응답은 2xx (최고 204) 입니다.
임시 실패 수신기 - 5xx; 발신자가 반복합니다 (지수 백오프, 지터).
'이벤트 _ id' 에 의한 중복 제거 및 결과 저장 (dempotent 소비자).
잘못된 페이로드-400/422 재 시도 없음.

10) 프로토콜 적합성 (gRPC/GraphQL)

gRPC → HTTP는 다음과 같습니다

'INVALID _ ARGUMENT' → 400

'UNAUTHENTICATED' → 401

'PERMISSION _ DENIED' → 403

'NOT _ FOUND' → 404

'ALREADY _ EXISTS' → 409

'FAILED _ PRECONDITION' → 412/422

'RESOURCE _ EXHAUSTED' → 429

'ABORTED' → 409

'UNAVAILABLE' → 503

'DEADLINE _ EXCEEDED' → 504

GraphQL: 전송 계층에서 항상 200 개가 유효하지만 '오류 []' 에 오류가 있고 헤더/확장에 중복됩니다

json
{
"data": { "createPayment": null },
"errors": [{
"message": "Forbidden",
"extensions": { "code": "FORBIDDEN", "status": 403, "trace_id": "..." },
"path": ["createPayment"]
}]
}

중요한 오류는 200 대신 해당 HTP 코드를 사용하는 것이 좋습니다.

11) 타이틀 및 고객 팁

'재시도 후' - 초/신호일 (429/503/425/408).
'경고' - 부드러운 열화 또는 제거 ("199 - Feature X가 우울합니다").
'Deprencation', 'Sunset', 'Link: <...>; rel = "deprecation" '-제어 종료시.
'문제 유형' (사용자 정의) -클라이언트에서 빠른 오류 라우팅.
'X-Trace-ID '/' Correlation-ID' -로그/추적 링크.

12) 메시지 보안

응답 기관에서 입력 비밀 (토큰/서명) 을 반복하지 마십시오.
마스크 PAN/PII ('1234').
401/403의 경우 실패한 속성을 공개하지 마십시오.
404의 경우 "자원은 존재하지만 귀하는 존재하지 않습니다" 대신 404에 불과합니다.

13) 오류 관찰 가능

• 'http _ orms _ total {상태, 경로, 테넌트}'
• (PHP 3 = 3.0.6, PHP 4)
• 공유 429, 5xx; 잘못된 답변을 별도로 'p95 '/' p99' 대기 시간
• 반복 팁의 히스토그램

• 응답을 'trace _ id', 저장 '코드', '유형', '상태', '경로', '테넌트', PII 없음과 연관시킵니다.

• RPS> N에서 스파이크 '5xx _ rate> X%';
• 중요한 경로에서 429의 성장;
• '타임 아웃/504' 종속성;
• 빈번한 409/dedempotency → 경주의 표시.

14) 예

14. 1,422 (사업 검증)

json
{
"type": "https://errors.example.com/payments/limit-exceeded",
"title": "Limit exceeded",
"status": 422,
"code": "PAYMENT_LIMIT_EXCEEDED",
"detail": "Daily withdrawal limit reached for KYC1.",
"hint": "Increase limits after KYC2 or try tomorrow.",
"trace_id": "01J5...XYZ"
}

14. 2,409 (demempotency)

HTTP/1.1 409 Conflict
Idempotency-Replay: true

json
{
"type": "https://errors.example.com/idempotency/replay",
"title": "Duplicate request",
"status": 409,
"code": "IDEMPOTENT_REPLAY",
"detail": "A request with the same Idempotency-Key was already processed.",
"hint": "Reuse the same Idempotency-Key and GET the operation status."
}

14. 3,429 (제한)

json
{
"type":"https://errors.example.com/rate/too-many-requests",
"title":"Too many requests",
"status":429,
"code":"RATE_LIMITED",
"detail":"Per-key rate limit exceeded.",
"hint":"Retry after the time specified in Retry-After header."
}

15) 안티 패턴

신체 오류 텍스트를 사용하여 200을 반환

서비스간에 다른 오류 형식을 혼합하십시오

스택/SQL/테이블 이름/내부 탭을 '세부' 으로 확장하십시오.
안정적인 '코드 '/' 유형' 대신 '메시지' 를 사용하십시오.
예상 비즈니스 오류가 발생하면 500을 반환합니다 (예: "밸런스가 충분하지 않음").
REST/GraphQL/gRPC 간의 일관되지 않은 의미론.

16) iGaming/Finance의 세부 사항

KYC/AML/제재에 대한 명확한 코드: 'KYC _ REQUIRED', 'KYC _ REVIEW', 'AML _ LOCK', 'SANCTION _ BLOCKED'.
법적 제한: 451 목록없이 안전한 문구가 있습니다.
통화 쓰기 작업: 경쟁 및 잠금을위한 409/423, 리도 창이있는 '힌트'.
플레이어 제한 불변: 책임있는 지불 위반에 422를 사용하십시오.
감사: 변경 불가능한 솔루션 로그 (코드, 시간, 액터, trace _ id).

17) Prod 준비 점검표

• 단일 JSON 오류 체계, 안정적인 '유형 '/' 코드'.
• 신호음 gRPC/GraphQL 매핑은 일관되고 문서화되어 있습니다.
• Retray semantics + 'Reduction-After'; 쓰기에 대한 dempotency.
• PII/비밀 마스킹; 자원을 숨기려면 404입니다.
• 오류 및 경고 메트릭; 'trace _ id' 와의 상관 관계.
• 우울한 정책: 'Deprencation', 'Sunset', 'Link'.
• 테스트: 음수/퍼즈, 버전 충돌, 의존성 감소, 이중 제출.
• 고객 안내서: 백오프 예 및 409/422/429/5xx 처리.

18) TL; DR

'유형 '/' 코드 '/' 추적 _ id' 로 단일 JSON 오류 형식을 표준화하고 올바른 번호를 사용하고 검증 (400/422), (401/403/404 권리), 충돌/demempotency (409) 및 제한 (429). '재시도 후' 및 '힌트' 를 명확하게하고, 민감한 데이터를 마스크하고, 'trace _ id' 로 오류를 기록하고 5xx/429/p99로 경고를 작성하십시오.