Cloud recognition apis 오류 코드 설명
응답 형식
모든 API 응답은 통일된 JSON 형식을 사용하며, 다음은 예시입니다:
{
"statusCode": 422,
"reuslt": "The image or meta exceeds its maximum permitted size",
"timestamp": 1514736000000,
"appKey": "test_app_key"
}
| 필드 | 타입 | 설명 |
|---|---|---|
| statusCode | integer | 비즈니스 상태 코드. 0은 성공, 0이 아닌 값은 오류 |
| result | string | 반환 내용. 상태 코드가 0일 때 대상 이미지 객체 구조, 그 외에는 오류 메시지 |
| timestamp | long | 서버 Unix 형식 타임스탬프(밀리초 단위) |
중요
statusCode == 0 조건에서만 result에 응답 내용이 포함되며, 그 외 상태에서는 result에 오류 메시지가 반환됩니다.
오류 코드 분류
HTTP 상태 코드 설명
| HTTP 상태 코드 | 설명 |
|---|---|
| 200 | 요청 성공(비즈니스 오류 포함 가능) |
| 400 | 요청 매개변수 오류 |
| 401 | APIKey 인증 실패 |
| 403 | 권한 부족 또는 리소스 접근 금지 |
| 404 | 요청 URL 인터페이스 경로 없음 |
| 500 | 서버 내부 오류 |
| 501 | 애플리케이션 예외 발생, 데이터 오류 가능 |
| 502 | 서버 사용 불가, 고객센터 문의 |
참고
비즈니스 오류는 일반적으로 HTTP 200 응답으로 반환되며, statusCode 필드에서 구체적인 오류 유형을 식별합니다.
비즈니스 상태 코드 목록
| Status Code | Message |
|---|---|
| 0 | ok |
| 1 | invalid appId (appKey) |
| 2 | invalid signature |
| 3 | invalid date |
| 4 | appId (appKey) not exist |
| 6 | invalid token |
| 6 | invalid appkey token |
| 7 | non-sdk client for dau databases |
| 8 | Dau databases are not compatible with sense-4.6+ any more. |
| 404 | Target not found |
| 414 | Parameter required not exists or not correct |
| 422 | The image or meta exceeds its maximum permitted size |
| 417 | fail to add image |
| 419 | Cannot update target in database because similar target exists. |
| 420 | Target delete failed |
| 424 | Target enable error |
| 403 | Target already exists |
| 426 | Judge exceeds maxium candidates |
| 427 | Image not correct |
일반적인 오류 시나리오
응답 시간 초과
- Request Timeout: 네트워크 속도 저하. 클라이언트 네트워크 환경 점검 권장
인증 관련 오류
- Http 401 Unauthorized: APIKey 인증 실패. appId/appKey 정확성 확인 필요
- 상태 코드 401: 애플리케이션 키 무효 또는 존재하지 않음. 앱 설정 확인
매개변수 오류
- 400 Bad Request: 요청 매개변수 형식 오류
- 상태 코드 414: 필수 매개변수 누락 또는 값 요구사항 불일치
리소스 작업 오류
- 상태 코드 404: 조회 대상 리소스 없음
- 상태 코드 403: 대상 이미 존재. 중복 생성 불가
- 상태 코드 417/420/424: 추가/삭제/수정 작업 실패
파일 관련 오류
- 상태 코드 422: 업로드 파일 크기 제한 초과
- 상태 코드 427: 이미지 형식 미지원 또는 파일 손상
시스템 오류
- Http 500 Internal Server Error: 서버 내부 예외. 웹사이트 또는 샘플 테스트 권장
- Http 501 Exception: 애플리케이션 예외 발생. 데이터 오류 가능성. 웹사이트 또는 샘플 테스트 권장
- Http 502 Server: 서비스 응답 오류. 서버 장애 가능성. 고객센터 문의 권장
모범 사례 제안
- 클라이언트 처리: HTTP 상태 코드만으로 판단하지 말고
statusCode필드로 비즈니스 성공 여부 확인 권장 - 오류 재시도: 5xx 오류는 적절히 재시도, 4xx 오류는 요청 매개변수 점검 필요
- 로그 기록: 문제 진단을 위해 완전한 오류 응답 기록 권장
- 타임아웃 처리: 과도한 대기를 피하기 위해 적절한 요청 타임아웃 설정