오류 처리
HTTP 상태 코드와 오류 응답 본문을 함께 확인해 오류 상황을 정확히 처리하세요.
상태 코드
| 코드 | 설명 |
|---|---|
| 200 | 요청 성공 |
| 201 | 리소스 생성 성공 |
| 202 | 요청을 기다리는 상태 |
| 400 | 잘못된 요청 또는 JSON |
| 401 | API 키가 없거나 올바르지 않음 |
| 403 | API 키 종류가 다르거나 비활성화됨 |
| 404 | 리소스 또는 경로를 찾을 수 없음 |
| 409 | 요청 상태 충돌 |
| 422 | 외부 서비스에서 요청이 거절됨 |
| 429 | 요청 제한 초과 |
| 502 | 외부 서비스 처리 실패 |
| 503 | 서비스 또는 의존 시스템 사용 불가 |
| 504 | 외부 서비스 응답 시간 초과 |
오류 응답 본문
4xx/5xx 응답은 항상 다음과 같은 형식의 JSON 본문을 포함합니다.
공통 오류 응답 형식
{
"error": "invalid_bearer_token",
"message": "invalid API key"
}429 응답과 Retry-After
429 응답에는 Retry-After 헤더가 포함될 수 있습니다. 이 헤더는 다시 요청 가능한 시간을 초 단위로 알려줍니다. 해당 시간이 지난 후에 재시도하세요.
5xx 응답 재시도 시 주의
502/503/504와 같은 응답을 받았다고 해서 요청이 처리되지 않았다고 단정하지 마세요. 특히 외부 서비스와 연동되는 엔드포인트(PIN 충전, 이메일 발송 등)는 타임아웃 이후에도 실제로는 처리가 완료되었을 수 있습니다. 무조건적인 자동 재시도는 중복 처리를 유발할 수 있으니 각 엔드포인트 문서의 안내를 먼저 확인하세요.