상태 및 오류 처리 · 옴니ID 개발자 문서

옴니ID 연동에서 가맹점이 처리해야 하는 세션 상태, 오류 응답 형식, 결과 조회 failure_code와 권장 대응을 설명합니다. 각 API가 반환하는 HTTP 오류 코드는 OmniID API, 가맹점 바이오 API가 반환해야 하는 오류 코드는 가맹점 바이오 API를 확인해 주세요.

세션 상태#

가맹점 Backend는 GET /v1/sessions/{session_id}/result 응답의 status로 진행 여부를 판단합니다.

Status	Final	의미	가맹점 처리
`created`	no	세션이 생성됨	잠시 후 다시 조회
`opened`	no	사용자가 Hosted UI에 진입함	잠시 후 다시 조회
`app_launched`	no	바이오 인증앱이 실행됨	잠시 후 다시 조회
`callback_received`	no	앱 처리 결과를 수신함	잠시 후 다시 조회
`processing`	no	등록 저장 또는 확인 처리 중	잠시 후 다시 조회
`succeeded`	yes	처리가 정상적으로 완료됨	`mode`와 `result` 확인
`failed`	yes	시스템 또는 연동 처리에 실패함	`failure_code`에 따라 대응
`expired`	yes	세션이 만료됨	새 세션으로 다시 시작
`canceled`	yes	사용자 또는 가맹점이 취소함	필요하면 새 세션으로 다시 시작

succeeded, failed, expired, canceled는 최종 상태입니다. 최종 상태가 된 세션은 다시 처리되지 않으며, 재시도가 필요하면 새 세션을 생성해야 합니다.

성공 결과 판단#

최종 성공 여부는 Frontend 메시지나 Hosted UI 화면이 아니라 가맹점 Backend의 결과 조회 응답으로 판단해야 합니다.

조건	의미	가맹점 처리
`status=succeeded`, `mode=enroll`	바이오 등록 완료	`result.finger`를 사용자와 연결해 저장
`status=succeeded`, `mode=verify`, `result.matched=true`	바이오 확인 성공	서비스의 인증 성공 처리
`status=succeeded`, `mode=verify`, `result.matched=false`	처리는 정상 완료됐지만 바이오가 일치하지 않음	재시도 또는 대체 인증 안내

matched=false는 시스템 오류가 아니므로 status=failed로 취급하지 않습니다.

HTTP 오류 응답#

OmniID API의 HTTP 오류는 다음 형식으로 반환됩니다.

{
  "error": {
    "code": "invalid_token",
    "message": "Access token is invalid.",
    "request_id": "req_..."
  }
}

error.code를 기준으로 분기하고 message를 프로그램 로직에 사용하지 마세요.
request_id는 문의와 장애 추적에 사용합니다. 응답의 X-Request-Id 헤더와 같은 값입니다.
요청별 HTTP 상태와 error.code 목록은 OmniID API의 각 endpoint를 확인해 주세요.

HTTP 오류와 세션 처리 실패는 서로 다릅니다. API 요청 자체가 실패하면 HTTP 오류 응답이 반환됩니다. API 요청은 성공했지만 세션 처리가 최종적으로 실패하면 결과 조회 응답이 status=failed와 failure_code를 반환합니다.

결과 조회 실패 코드#

status=failed 또는 status=expired일 때 결과 조회 응답에 failure_code가 포함되고 result는 null입니다.

{
  "session_id": "ver_01J...",
  "mode": "verify",
  "status": "failed",
  "failure_code": "provider_timeout",
  "result": null,
  "expires_at": "2026-07-02T13:10:00Z"
}

retryable은 같은 세션이나 같은 요청을 다시 보내라는 의미가 아닙니다. 새 세션을 만들어 다시 시도할 가치가 있는지를 나타냅니다.

Failure Code	Retryable	권장 대응	의미
`provider_callback_failed`	yes	새 세션으로 재시도 안내. 반복되면 지원 문의	바이오 인증앱이 실패를 반환함
`provider_callback_invalid`	yes	새 세션으로 재시도. 반복되면 지원 문의	바이오 인증앱의 처리 결과가 올바르지 않음
`bio_enrollment_not_found`	no	등록 flow로 유도	확인에 필요한 기존 등록 데이터가 없음
`merchant_bio_api_timeout`	yes	잠시 후 새 세션으로 재시도하고 가맹점 바이오 API 상태 점검	가맹점 바이오 API 응답 시간 초과
`merchant_bio_api_error`	no	사용자에게 일반 오류를 안내하고 가맹점 내부 조사	가맹점 바이오 API 처리 실패
`provider_timeout`	yes	잠시 후 새 세션으로 재시도 안내	바이오 확인 처리 시간 초과
`provider_error`	yes	잠시 후 새 세션으로 재시도. 반복되면 지원 문의	바이오 확인 처리 실패
`session_expired`	yes	새 세션을 생성해 다시 진행	세션 만료
`internal_error`	yes	잠시 후 새 세션으로 재시도. 반복되면 지원 문의	옴니ID 내부 처리 오류

suggested_action은 사용자에게 그대로 노출할 문구가 아니라 대응 방향입니다. 가맹점 서비스의 문체와 고객지원 정책에 맞게 안내 문구를 작성해 주세요.

재시도 원칙#

created, opened, app_launched, callback_received, processing은 실패가 아닙니다. 기존 세션의 결과를 잠시 후 다시 조회합니다.
failed, expired, canceled는 최종 상태입니다. 다시 진행하려면 새 세션을 생성합니다.
세션 생성 요청이 network error나 timeout으로 끝나 응답을 확인하지 못했다면 같은 Idempotency-Key와 같은 body로 재시도합니다.
bio_enrollment_not_found는 확인 재시도보다 바이오 등록이 먼저 필요합니다.
오류가 반복되면 request_id 또는 session_id를 포함해 지원 채널로 문의해 주세요.