오류 처리
이 가이드는 k-ID API에 대한 오류 처리를 다루며 일반적인 오류 코드, 오류 응답 형식 및 오류 처리 모범 사례를 포함합니다.
오류 응답 형식
모든 API 오류는 일관된 응답 형식을 따릅니다. 오류 응답에는 error 필드와 errorMessage 필드가 포함됩니다:
{
"error": "ERROR_CODE",
"errorMessage": "사람이 읽을 수 있는 오류 메시지"
}
HTTP 상태 코드
k-ID API는 API 요청 결과를 나타내기 위해 표준 HTTP 상태 코드를 사용합니다:
| 상태 코드 | 설명 | 발생 시점 |
|---|---|---|
| 200 | OK | 요청 성공 |
| 400 | Bad Request | 잘못된 요청 매개변수 |
| 401 | Unauthorized | 잘못되었거나 누락된 API 키 |
| 429 | Too Many Requests | 속도 제한 초과 |
| 500 | Internal Server Error | 서버 오류 |
일반적인 오류 코드
인증 오류
UNAUTHORIZED
상태: 401
설명: 잘못되었거나 누락된 API 키
{
"error": "UNAUTHORIZED",
"errorMessage": "Unauthorized"
}
일반적인 원인:
- Authorization 헤더 누락
- 잘못된 API 키 형식
- 만료된 API 키
해결 방법:
- API 키가 올바른지 확인
- 키가 활성화되어 있고 만료되지 않았는지 확인
- Authorization 헤더에 키가 올바르게 형식화되었는지 확인
요청 검증 오류
INVALID_INPUT
상태: 400
설명: 요청 검증 실패
{
"error": "INVALID_INPUT",
"errorMessage": "The age verification could not be found."
}
해결 방법:
- 검증 오류 세부 정보 검토
- 잘못된 필드 값 수정
- 유효한 값에 대한 API 문서 참조
리소스 오류
속도 제한 오류
상태: 429
설명: 속도 제한 초과
응답 본문 없음
해결 방법:
- 지수 백오프 구현
- 요청 빈도 감소
- 적절한 경우 응답 캐싱
서버 오류
상태: 500
설명: 내부 서버 오류
{
"error": "INTERNAL_ERROR",
"errorMessage": "Internal server error"
}
해결 방법:
- 지연 후 요청 재시도
- 오류가 지속되면 지원팀에 문의
- 서비스 상태 페이지 확인