오류 코드
이 페이지는 오류 처리를 위한 단일 정보 출처입니다. SDK별 오류 코드는 각 SDK의 오류 처리 페이지에 문서화되어 있습니다. 이 페이지는 API 계약 수준의 오류를 다룹니다.
HTTP 상태 코드
| 코드 | 의미 | 적용 대상 |
|---|---|---|
200 OK | 요청 성공. | 모든 계약. |
201 Created | 리소스 생성됨(드문 경우; 대부분의 생성은 200 반환). | API 계약. |
400 Bad Request | 페이로드가 잘못되었거나 필수 필드가 누락됨. 본문에서 문제가 있는 필드를 확인할 수 있습니다. | 모든 계약. |
401 Unauthorized | 인증이 없거나, 만료되었거나, 유효하지 않음. | 모든 계약. |
403 Forbidden | 인증은 유효하지만 테넌트가 요청된 리소스에 대해 활성화되어 있지 않음(예: APIKEY에 없는 기능 호출). | Web & SDK, API. |
404 Not Found | 리소스가 존재하지 않거나 인증된 테넌트에 속하지 않음. | 모든 계약. |
409 Conflict | 리소스는 존재하지만 이 작업에 적합한 상태가 아님(예: 아직 진행 중인 프로세스에서 문서 가져오기). | Web & SDK, API. |
410 Gone | 리소스가 보존 정책에 따라 삭제되었거나(문서 조회 엔드포인트), 프로세스가 존재하지만 오류 상태로 종료된 경우 — 프로세스 조회 참조. | 문서 조회 엔드포인트; API 프로세스 조회. |
429 Too Many Requests | 속도 제한에 도달했습니다. 지수 백오프로 재시도하세요. | 모든 계약. |
5xx | 플랫폼 오류. 백오프로 재시도하세요. 지속되는 경우 응답 본문과 타임스탬프와 함께 지원팀에 문의하세요. | 모든 계약. |
인증 오류(401)
| 원인 | 증상 |
|---|---|
| 잘못된 개인 키(잘못된 키로 어서션 서명) | 401, Authentication failed (1.2.21) |
aud가 환경 URL과 일치하지 않음 | 401 |
과거의 exp 클레임 | 401, Authentication failed |
지원되지 않는 알고리즘(RS256 사용) | 401 |
| 샌드박 스/프로덕션 자격 증명 혼용 | 401(자격 증명이 올바르게 보이더라도) |
APIKEY 헤더 누락(API 계약 전용) | 401 |
유효하지 않은 x-api-key(Magic Link 전용) | 401 |
전체 문제 해결 체크리스트는 인증 > 일반적인 오류를 참조하세요.
기능 수준 결과(부정적 결과가 있는 200)
200 OK가 사용자가 인증을 통과했다는 의미는 아닙니다 — 플랫폼이 작업을 완료했다는 의미입니다. 사용자 대면 결정은 HTTP 상태가 아닌 응답 본문에 있습니다:
| 필드 | 부정적 값 | 나타나는 위치 |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.response.unico.result | NOT_APPROVED | Magic Link |
재시도 정책
| 상태 | 재시도 여부 | 방법 |
|---|---|---|
5xx | 예 | 지수 백오프(1s, 2s, 4s, 8s, …). 최대 5회 시도. |
429 | 예 | Retry-After 헤더가 있으면 준수; 없으면 지수 백오프. |
4xx(기타) | 아니오 | 요청이 잘못됨. 재시도 전에 입력을 수정하세요. |
401 | 조건부 | 액세스 토큰을 한 번 갱신하세요. 새 요청도 401을 반환하면 구조적 문제입니다 — 재시도하지 마세요. |
멱등성
IDCloud 플랫폼은 현재 생성 엔드포인트에 멱등성 키 메커니즘을 노출하지 않습니다. POST /client/v1/process 또는 POST /processes/v1 재시도 시 주의하세요 — 5xx의 네트워크 오류가 실제로 서버 측에서 성공했을 수 있으며, 재시도하면 중복 프로세스가 생성됩니다. 의심스러운 경우 재시도 전에 내부 상관 ID로 최근 프로세스를 조회하세요.
SDK 오류가 있는 곳
Web SDK, Android SDK, iOS SDK, Flutter SDK의 오류 목록은 각 SDK의 전용 오류 처리 페이지에 문서화되어 있습니다:
이들은 여기에 문서화된 API 측 오류와는 별개로 장치 측 오류(카메라 권한 거부, 캡처 타임아웃, 장치의 네트워크 연결 불가)를 다룹니다.