--- title: 오류 코드 description: Web & SDK, API, Magic Link 계약에 걸친 HTTP 및 플랫폼 오류 코드의 통합 목록. canonical: https://developer.unico.io/ko/dual-api/developers/api-reference/error-codes locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - [API 레퍼런스](/ko/dual-api/developers/api-reference/) - 오류 코드 **이 페이지에서# 오류 코드 이 페이지는 오류 처리를 위한 단일 정보 출처입니다. SDK별 오류 코드는 각 SDK의 [오류 처리](/ko/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) 페이지에 문서화되어 있습니다. 이 페이지는 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`리소스가 보존 정책에 따라 삭제되었거나(문서 조회 엔드포인트), 프로세스가 존재하지만 오류 상태로 종료된 경우 — [프로세스 조회](/ko/dual-api/developers/api-reference/api/get-process) 참조.문서 조회 엔드포인트; API 프로세스 조회.`429 Too Many Requests`[속도 제한](/ko/dual-api/developers/api-reference/rate-limits)에 도달했습니다. 지수 백오프로 재시도하세요.모든 계약.`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` 전체 문제 해결 체크리스트는 [인증 > 일반적인 오류](/ko/dual-api/developers/api-reference/authentication#error-codes)를 참조하세요. ### 기능 수준 결과(부정적 결과가 있는 `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의 전용 **오류 처리** 페이지에 문서화되어 있습니다: [Web SDK > 오류 처리](/ko/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) [Android SDK > 오류 처리](/ko/developers/sdks-and-tools/android/error-handling) [iOS SDK > 오류 처리](/ko/developers/sdks-and-tools/ios/error-handling) [Flutter SDK > 오류 처리](/ko/developers/sdks-and-tools/flutter/error-handling) 이들은 여기에 문서화된 API 측 오류와는 별개로 장치 측 오류(카메라 권한 거부, 캡처 타임아웃, 장치의 네트워크 연결 불가)를 다룹니다.마지막 업데이트 2026년 10월 8일**에