상태, 유형, 발생 사례 구분
RFC 9457은 application/problem+json을 정의합니다. 안정된 문제 유형과 사례별 설명을 쓰세요. 클라이언트가 번역된 문장을 분석해 행동을 정하게 해서는 안 됩니다. status가 있다면 실제 HTTP 상태와 일치시켜야 합니다.
| 상태 | HTTP 의미 | 검토할 처리 |
|---|---|---|
| 400 | 잘못된 요청 | 수정 후 재시도. |
| 401 | 유효한 인증 정보 없음 | 자격 증명과 정해진 방식을 확인. |
| 403 | 이해했지만 거부한 요청 | 권한 확인. 반복해도 권한은 생기지 않음. |
| 503 | 서비스 일시 이용 불가 | 작업이 허용하면 제한된 대기와 재시도. |
실패 경로 예측 가능하게 만들기
- 코드, 형식, 기대 처리를 문서화하세요. 빈 응답, 게이트웨이의 비 JSON, 연결 중단, 시간 초과도 시험하세요.
- 서버에서 입력과 권한을 검증하세요. 예상 실패는 처리하되 미지의 장애를 숨기지 말고 업무 실패를 성공 응답으로 감추지 마세요.
- 지원팀용 상관관계 식별자를 반환하세요. 스택, 내부 질의, 비밀번호, 토큰은 공개 응답에 넣지 마세요.
의미 있을 때만 재시도
5xx는 무한 재시도를 허용하지 않습니다. 계약, 작업 상태, 멱등성, 전체 기한을 함께 판단하세요. 민감 정보를 제거한 최소 재현으로 결함을 보고하고, 수정 후 원래 사례와 관련 접근 거부를 다시 시험하세요.
1차 자료
API 오류는 정보 유출 없이 조치를 안내해야 합니다.
HTTP 상태는 초기 범주를 제공하지만 클라이언트는 안정적인 유형과 유용한 세부 정보가 필요할 수 있습니다. RFC 9457은 일반적인 문제 구조를 설명하지만 내부 추적이나 민감한 데이터를 노출하는 것을 정당화하지는 않습니다.
- 영구 거부, 수정 가능한 입력 및 일시적 오류를 구분합니다.
- 각 중요한 오류에 대해 유형, 상태 및 가능한 클라이언트 조치를 문서화합니다.
- 응답에 비밀 정보나 불필요한 전체 페이로드가 포함되지 않는지 테스트합니다.
1차 자료: IETF RFC 9457 — Problem Details for HTTP APIs. 관련 방법: 실무 가이드 읽기.
API 재시도: 전체 시간 예산 계산하기
호출 상한과 전체 기한을 정하세요.
가상의 교육용 사례로 CIE나 고객 실적이 아닙니다.
가상 모델은 호출 네 번 각 최대 250밀리초, 대기 100, 200, 400입니다. 지터, 연결, 대기열, 로컬 검증은 제외됩니다.
- 총 시도
- 41 + 3
- 누적 대기(ms)
- 700100 + 200 + 400
- 모델 예산(ms)
- 17004 × 250 + 700
| 단계 | 최대 호출(ms) | 다음 대기(ms) |
|---|---|---|
| 시도 1 | 250 | 100 |
| 시도 2 | 250 | 200 |
| 시도 3 | 250 | 400 |
| 시도 4 | 250 | 0 |
| 합계 | 1000 | 700 |
- 호출 시간1,000
- 누적 대기700
- 전체 기한(ms)1,500
결론 전 확인
- 1,000 + 700 = 1,700은 기한 1,500밀리초를 넘습니다.
- 전체 기한을 전달하고 중복 효과를 막으세요. 시간 초과는 원격 취소를 입증하지 않습니다.
재시도 시간 예산 계산
n × T + W × (2^(n−1) − 1)
관련 방법: 실무 가이드 읽기.
API 오류: 유형, 상태 및 증거
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5