오류 코드
이 페이지는 오류 처리를 위한 단일 정보 출처입니다. SDK별 오류 코드는 각 SDK의 오류 처리 페이지에 문서화되어 있습니다. 이 페이지는 API 계약 수준의 오류를 다룹니다.
HTTP 상태 코드
| 코드 | 의미 |
|---|---|
200 OK | 요청 성공. |
400 Bad Request | 페이로드가 잘못되었거나 필수 필드가 누락됨. 본문에서 문제가 있는 필드를 확인할 수 있습니다. |
401 Unauthorized | 인증이 없거나, 만료되었거나, 유효하지 않음. |
403 Forbidden | 인증은 유효하지만 테넌트가 요청된 리소스에 대해 활성화되어 있지 않음(예: APIKEY에 없는 기능 호출). |
404 Not Found | 리소스가 존재하지 않거나 인증된 테넌트에 속하지 않음. |
409 Conflict | 리소스는 존재하지만 이 작업에 적합한 상태가 아님(예: 아직 진행 중인 프로세스에서 문서 가져오기). |
410 Gone | 리소스가 보존 정책에 따라 삭제되었거나(문서 조회 엔드포인트), 프로세스가 존재하지만 오류 상태로 종료된 경우 — 프로세스 조회 참조. |
429 Too Many Requests | 속도 제한에 도달했습니다. 지수 백오프로 재시도하세요. |
5xx | 플랫폼 오류. 백오프로 재시도하세요. 지속되는 경우 응답 본문과 타임스탬프와 함께 지원팀에 문의하세요. |
재시도 정책
| 상태 | 재시도 여부 | 방법 |
|---|---|---|
5xx | 예 | 지수 백오프(1s, 2s, 4s, 8s, …). 최대 5회 시도. |
429 | 예 | Retry-After 헤더가 있으면 준수; 없으면 지수 백오프. |
4xx(기타) | 아니오 | 요청이 잘못됨. 재시도 전에 입력을 수정하세요. |
401 | 조건부 | 액세스 토큰을 한 번 갱신하세요. 새 요청도 401을 반환하면 구조적 문제입니다 — 재시도하지 마세요. |
멱등성
IDCloud 플랫폼은 현재 생성 엔드포인트에 멱등성 키 메커니즘을 노출 하지 않습니다. 프로세스 생성 재시도 시 주의하세요 — 5xx의 네트워크 오류가 실제로 서버 측에서 성공했을 수 있으며, 재시도하면 중복 프로세스가 생성됩니다. 의심스러운 경우 재시도 전에 내부 상관 ID로 최근 프로세스를 조회하세요.
SDK 오류가 있는 곳
Android SDK, iOS SDK, Flutter SDK의 오류 목록은 각 SDK의 전용 오류 처리 페이지에 문서화되어 있습니다:
이들은 여기에 문서화된 API 측 오류와는 별개로 장치 측 오류(카메라 권한 거부, 캡처 타임아웃, 장치의 네트워크 연결 불가)를 다룹니다.