> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 라이브니스 감지 경고 및 오류 코드

> Didit의 라이브니스 모듈에서 발생하는 모든 경고(얼굴 공격, 낮은 점수 및 품질 트리거, 차단 목록 일치, 중복 얼굴)의 원인과 해결 방법을 확인하세요.

## 개요

라이브니스 보고서의 경고는 Didit이 라이브니스 확인을 실행하는 동안 감지한 모든 조건을 표시합니다. 경고는 `feature`가 `"LIVENESS"`로 설정된 상태로 `liveness_checks[]`의 각 항목 내 `warnings[]` 배열에 포함됩니다([라이브니스 보고서](https://docs.didit.me/ko/core-technology/liveness/report-liveness.md) 참조). 각 항목은 공통 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태(`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`)를 따릅니다.

모든 경고에는 세 가지 계층이 있습니다.

1. **`risk` 코드** — 코드에서 일치 여부를 확인할 수 있는 고유 식별자(아래 나열된 코드).
2. **`log_type`** — `information`, `warning`, `error` 중 하나입니다. 자동 거부 위험에는 항상 `error`가 부여됩니다. 구성 가능한 위험의 경우 설정된 작업에 따라 결정됩니다. **작업 없음** → `information`, **검토** → `warning`, **거부** → `error`. 임계값 기반 위험(`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`)의 경우 값이 거부 임계값 이하이면 `error`, 검토 임계값 이하에만 해당하면 `warning`이 됩니다.
3. **결정 영향** — 동일한 라우팅이 라이브니스 보고서의 `status`를 결정합니다. 검토 작업은 `In Review`로, 거부 작업(또는 모든 자동 거부 위험)은 `Declined`로 변경하며, 작업 없음은 상태를 그대로 유지합니다.

일부 위험은 라이브니스 방식이 `PASSIVE`일 때만 발생합니다(다중 얼굴, 품질 및 휘도 확인). 아래 표에는 전체 라이브니스 위험 코드와 해당 심각도가 나열되어 있으며, 여기에 없는 다른 라이브니스 위험 코드는 존재하지 않습니다.

## 자동 거부 조건

다음 위험은 항상 `log_type: "error"`와 함께 라이브니스 보고서(및 세션)를 `Declined` 상태로 강제 변경합니다.

| 위험 | 트리거 |
| - | - |
| `NO_FACE_DETECTED` | 라이브니스 캡처 중 얼굴을 찾지 못했거나 사용자가 재시도 횟수를 모두 소진했습니다. |
| `LIVENESS_FACE_ATTACK` | 모델이 프레젠테이션 공격(가면, 화면 재생, 딥페이크 계열 스푸핑)을 감지했습니다. |
| `FACE_IN_BLOCKLIST` | 얼굴이 애플리케이션의 얼굴 차단 목록에 등록된 항목과 일치했습니다. |
| `AGE_BELOW_MINIMUM` | 추정 연령이 설정된 최소 연령 미만입니다. 적응형 연령 확인 워크플로 및 `AGE_ESTIMATION` 노드에서만 발생합니다. |
| `AGE_NOT_DETECTED` | 연령을 추정할 수 없습니다. 신분증 인증 대체가 비활성화된 연령 추정 플로우에서만 발생합니다. |

`NO_FACE_DETECTED`가 발생하면 `LOW_LIVENESS_SCORE`는 생략됩니다(점수를 산정할 얼굴이 없기 때문입니다).

## 구성 가능한 인증 설정

Didit 콘솔에서 라이브니스 위험은 다음과 같은 워크플로 설정으로 그룹화됩니다.

| 그룹 | 위험 | 구성 |
| - | - | - |
| **라이브니스 점수 임계값** | `LOW_LIVENESS_SCORE` | `score`에 대한 검토 임계값 + 거부 임계값. 검토 이하 → `In Review`, 거부 이하 → `Declined`. |
| **중복 얼굴 작업** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | 하나의 공유 설정: 작업 없음(기본값) / 검토 / 거부. 일치하는 얼굴이 얼굴 허용 목록에 있으면 완전히 건너뜁니다. |
| **중복 얼굴 신원 불일치** | `DUPLICATED_FACE_NAME_MISMATCH` | 자체 설정(`face_liveness_duplicated_face_name_mismatch_action`): 작업 없음 / 검토(기본값) / 거부. `DUPLICATED_FACE`도 함께 발생한 경우에만 평가됩니다(아래 참조). |
| **라이브니스 공격 얼굴 대조** | `FACE_MATCHES_LIVENESS_ATTACK` | 자체 설정(`face_liveness_attack_face_match_action`): 작업 없음(기본값) / 검토. 여기서 거부로 설정해도 검토로 적용됩니다. 연령 추정 노드에서도 사용할 수 있습니다. |
| **차단 목록 등록 의심 얼굴** | `POSSIBLE_FACE_IN_BLOCKLIST` | 워크플로에서 구성할 수 없으며, 항상 검토로 라우팅됩니다(`log_type: "warning"`). |
| **다중 얼굴 감지 작업** *(수동형 전용)* | `MULTIPLE_FACES_DETECTED` | 작업 없음(기본값) / 검토 / 거부. |
| **얼굴 품질 임계값** *(수동형 전용)* | `LOW_FACE_QUALITY` | 검토 임계값(기본값 15) + 거부 임계값(기본값 0, 즉 거부 비활성화). |
| **얼굴 밝기** *(수동형 전용)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | 최소/최대 임계값(정규화된 0–100 스케일 기준 기본값 20 / 80) + 방향별 작업(기본값 검토). |
| **연령 임계값** *(적응형 워크플로 / `AGE_ESTIMATION` 노드)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | 최소 연령 및 경계 연령 임계값. 두 위험 모두 라이브니스 단계를 자동 거부합니다. 신분증 인증 대체가 활성화된 경우 워크플로는 세션을 종료하는 대신 사용자를 신분증 확인 단계로 라우팅합니다. |

## 생성되는 경고

### 핵심 라이브니스

| 위험 | 원인 | 심각도 | 상태에 영향을 주나요? | 조치 방법 |
| - | - | - | - | - |
| `NO_FACE_DETECTED` | 캡처 중 얼굴이 감지되지 않았거나 사용자가 재시도 횟수를 모두 소진했습니다(`MAX_ATTEMPTS_REACHED`). | `error` | **자동 거부** | 조명이 더 좋은 환경에서 다시 캡처하고, 얼굴이 중앙에 오도록 하십시오. |
| `LIVENESS_FACE_ATTACK` | 모델이 프레젠테이션 공격을 감지했습니다. | `error` | **자동 거부** | 사기 시도로 처리하십시오. 세션이 자동으로 거부됩니다. |
| `LOW_LIVENESS_SCORE` | `score`가 워크플로의 검토 임계값 이하입니다. `NO_FACE_DETECTED`도 함께 나타나는 경우에는 억제됩니다. | `warning`. 점수가 거부 임계값 이하인 경우 `error`로 격상됨 | 설정 가능(검토 / 거부 임계값) | 다시 캡처하십시오. 오탐이 발생하는 경우 임계값을 조정하십시오. |

### 캡처 채널 무결성

캡처 시 클라이언트에서 보고하는 인젝션 공격 신호입니다. 프레젠테이션 공격(실제 카메라 앞에 인공물을 가져다 대는 행위)과 달리, 카메라 피드 자체가 대체되거나 가로채이는 상황을 나타냅니다.

각 항목은 워크플로별로 설정할 수 있으며 기본값은 **작업 없음**이므로, 직접 활성화하기 전까지는 이 기능을 켜도 결정이 변경되지 않습니다.

| 위험 | 원인 | 설정 키 | 기본값 |
| - | - | - | - |
| `VIRTUAL_CAMERA_DETECTED` | 캡처 기기가 물리적 카메라가 아닌 소프트웨어 가상 카메라(OBS, ManyCam, Snap Camera, DroidCam 등)로 식별되었습니다. | `virtual_camera_action` | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | 캡처 기기가 내장 카메라가 아닌 외장 카메라 또는 캡처 카드였습니다. | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED` | 캡처된 프레임에서 실제 라이브 캡처가 아닌 소프트웨어 합성 또는 카메라 파이프라인으로의 인젝션 징후가 나타났거나, **또는** 물리적 카메라 센서가 존재하지 않고 호스트에서 모든 프레임을 제공하는 에뮬레이션 또는 가상화된 하드웨어(Android 에뮬레이터 또는 데스크톱 가상 머신)에서 캡처가 수행되었습니다. | `frame_injection_action` | `NO_ACTION` |
| `INJECTION_ATTACK_DETECTED` | 기기 자체의 카메라로 캡처된 것이 아니라 소프트웨어 가상 카메라, 페이지나 브라우저 자동화로 생성된 카메라 피드, 후킹된 카메라, 또는 앱에 연결된 계측 도구 등을 통해 캡처가 인젝션되었습니다. `additional_data.reasons`에는 이를 입증하는 이유만 나열됩니다. 실제 사람이 생성할 수 있는 신호만으로는 절대 발생하지 않습니다. 라이브니스 및 얼굴 대조에서는 `frame_injection_action`을 따르므로 셀피 결정은 변경되지 않습니다. | `frame_injection_action` | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE` | 생체 인식 캡처 중에 기기에서 화면 녹화 또는 화면 공유가 활성화되어 있었습니다. | `screen_capture_action` | `NO_ACTION` |

> [!NOTE]
>
> 브라우저는 어떤 벤더에게도 OS 수준의 카메라 소스 증명을 제공하지 않으므로, 웹에서 이러한 신호는 직접적인 증거라기보다는 뒷받침하는 정황 증거입니다. 웹에서 `null` 판정은 **판정 불가**(카메라 권한이 부여될 때까지 기기 라벨을 사용할 수 없음)를 의미하며 절대 위험을 발생시키지 않습니다.

가상 카메라는 기기 이름으로 식별되므로, 운영체제에서 일반적인 이름으로 표시하는 카메라는 이러한 방식으로 인식되지 않습니다. Android 에뮬레이터 내부에서는 재매핑된 카메라가 일반 내장 카메라처럼 라벨링되므로, 에뮬레이트된 하드웨어 케이스는 대신 `FRAME_INJECTION_SUSPECTED`를 통해 보고됩니다. 즉, 카메라 이름이 아니라 기기 환경(렌더링 스택 및 사용자 에이전트에 보고된 기기 모델)을 통해 감지됩니다. 기기 환경에서 발생한 탐지 결과에는 `additional_data.reason: "emulated_capture_device"`가 포함되어 라이브니스 모델 자체의 프레임 분석과 구별됩니다.

> [!NOTE]
>
> 브라우저를 통해 머신을 감지하는 것은 정황 증거일 뿐 공식적인 증명이 아니며, 작정한 공격자라면 이를 방해할 수 있습니다. 네이티브 모바일 SDK는 브라우저에서는 볼 수 없는 더 강력한 운영체제 수준의 무결성 신호(에뮬레이터, 루팅 또는 탈옥 기기, 런타임 후킹, 연결된 디버거)를 보고하며, 각각 [기기 및 런타임 무결성](https://docs.didit.me/ko/core-technology/ip-analysis/warnings-ip-analysis.md#기기-및-런타임-무결성)에서 자체적으로 구성 가능한 작업이 있습니다. 이러한 신호는 공격자의 비용을 상당히 증가시키지만, 단독으로는 캡처가 실제 기기에서 생성되었음을 증명하지 못합니다. 기기 무결성 신호는 라이브니스 방식과 무관하므로 Passive, 3D Flash 또는 3D Action & Flash 중 어느 방식과도 함께 사용할 수 있습니다.

### 녹화본 이상 여부 포렌식

`LIVENESS_VIDEO_ANOMALY`는 라이브니스 모델과 독립적으로 **저장된 라이브니스 녹화본에 대해 서버 측에서** 계산됩니다. 루프 피드와 일치하는 여러 주기에 걸쳐 반복되는 움직임 시퀀스를 감지합니다.

| 위험 | 원인 | 설정 키 | 기본값 |
| - | - | - | - |
| `LIVENESS_VIDEO_ANOMALY` | 녹화본에 반복되는 움직임 시퀀스가 포함되어 있습니다. 카메라 정지, 반복되는 정지 프레임, 어두운 도입부, 느린 프레임 전송만으로는 이 신호가 발생하지 않습니다. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

라이브니스 또는 연령 추정 노드에서 작업을 설정하십시오. `NO_ACTION`은 정보 탐지 결과를 기록하고, `REVIEW`는 이미 결정된 인증의 상태를 검토 중으로 격상할 수 있으며, `DECLINE`은 거부됨으로 격상할 수 있습니다. 검사는 비동기식으로 실행되므로 초기 결과가 전달된 후에 상태가 격상될 수 있습니다. 기존의 더 심각한 결정은 하향 조정되지 않으며, 수동 검토 결정은 유지됩니다.

버전 2 탐지 결과에는 `forensics_version: 2`, `repeated_sequence` 증거 및 `anomaly_reasons`의 `repeated_moving_sequence`가 포함됩니다. `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio`, `max_frame_gap_seconds`와 같은 전송 측정값은 진단용으로 유지되며, 단독으로 재생 공격을 입증할 수는 없습니다. 이전 탐지 결과는 당시 사용된 탐지기 버전을 나타내며 소급하여 재분류되지 않습니다.

> [!NOTE]
>
> 이것은 보수적인 추가 신호이며, 합성 미디어 또는 인젝션된 동영상에 대한 완벽한 탐지는 아닙니다. 이상 징후가 없는 녹화본이라고 해서 라이브니스를 증명하는 것은 아닙니다. 짧거나 모호한 캡처 및 유효한 재생 증거가 없는 캡처는 이 검사에서 플래그가 지정되지 않습니다. 누락되었거나 읽을 수 없는 녹화본은 이 검사에서 탐지 결과를 생성하지 않으며, 다른 인증 검사는 여전히 적용됩니다.

### 세션 간 얼굴 대조

| 위험 | 원인 | 추가 데이터 | 심각도 |
| - | - | - | - |
| `FACE_IN_BLOCKLIST` | 얼굴이 차단 목록에 등록된 얼굴과 일치했습니다. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` — **자동 거부** |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 얼굴이 더 낮은 신뢰도 구간에서 차단 목록의 얼굴과 일치했습니다. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` — 워크플로에서 항상 검토(Review)로 라우팅됨 |
| `FACE_IN_ALLOWLIST` | 얼굴이 허용 목록에 등록된 얼굴과 일치했습니다. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — 중복 얼굴 작업 건너뜀 |
| `POSSIBLE_FACE_IN_ALLOWLIST` | 얼굴이 더 낮은 신뢰도 구간에서 허용 목록의 얼굴과 일치했습니다. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` — 중복 의심 얼굴 작업 건너뜀 |
| `DUPLICATED_FACE` | 얼굴이 다른 사용자의 이미 승인된 얼굴(다른 `vendor_data`를 가진 `Approved` 세션 또는 벤더 사용자 중 하나에 대해 가져온 얼굴)과 일치했습니다. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | 설정 가능 — 기본값 `information` |
| `POSSIBLE_DUPLICATED_FACE` | 얼굴이 더 낮은 신뢰도 구간에서 다른 승인되거나 가져온 얼굴과 일치했습니다. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | 설정 가능 — 기본값 `information` |
| `DUPLICATED_FACE_NAME_MISMATCH` | 신분증 인증과 동일한 성명 일치 점수 산정 및 임계값을 사용하여, 일치하는 세션의 신원 정보가 이 세션에서 확인된 성명(신분증 문서, `expected_details` 또는 연결된 벤더 사용자)과 일치하지 않을 때 `DUPLICATED_FACE`와 함께 발생합니다. 다른 성명으로 재사용된 얼굴은 단순 중복보다 더 강력한 사기 신호이므로 별도의 설정 가능한 작업이 적용됩니다. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | 설정 가능 — 기본값 `warning`. `DUPLICATED_FACE` 자체의 설정된 결과를 완화하지 않으며 에스컬레이션만 수행합니다. |
| `DUPLICATED_FACE_DOCUMENT_MISMATCH` | 일치하는 사용자의 신분증 문서에 표시된 생년월일이 이 세션의 문서와 다를 때 `DUPLICATED_FACE`와 함께 발생합니다. 동일한 인물이 다른 문서(예: 신분증 후 여권 제출)를 제시하거나 갱신된 문서를 제시하는 경우에는 플래그가 지정되지 않으며, 동일한 국가의 동일한 문서 번호를 공유하는 두 세션은 절대 플래그가 지정되지 않습니다. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions` | 설정 가능(`face_liveness_duplicated_face_document_mismatch_action`) - 기본값 `Review`. `DUPLICATED_FACE` 자체의 설정된 결과를 완화하지 않으며 에스컬레이션만 수행합니다. |
| `FACE_MATCHES_LIVENESS_ATTACK` | 얼굴이 이 애플리케이션의 이전 세션 중 다른 사용자의 얼굴과 일치하며, 해당 사용자의 라이브니스 캡처가 높은 신뢰도로 공격으로 판정된 경우입니다. 이는 검토를 위한 증거이며 공격의 확정적인 증거는 아닙니다. | `liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count` | 설정 가능 - 기본값 `information`(작업 없음) |

가져온 얼굴 또는 목록 항목 얼굴(세션이 없음)과의 일치 항목에 대해 `additional_data`의 `*_session_id`, `*_session_number`, `api_service` 값은 `null`입니다.

동일한 사용자(동일한 `vendor_data` 또는 사용 가능한 경우 동일한 벤더 사용자)에 속한 얼굴은 중복 감지 및 차단 목록 스크리닝을 포함한 **전체** 인덱스 검색에서 제외됩니다. 일치 우선순위는 다음과 같습니다: 차단 목록 정확 일치 → 허용 목록 정확 일치 → 중복 정확 일치 → 차단 목록 가능성 → 허용 목록 가능성 → 중복 가능성. 상호 배타적인 이 6개 코드 중 보고서당 하나만 표시됩니다. `DUPLICATED_FACE_NAME_MISMATCH`는 이 우선순위 그룹에 속하지 않습니다. 이는 신원 확인도 실패했을 때 기존 코드를 대체하는 것이 아니라 `DUPLICATED_FACE`에 **추가되어** 생성되는 코드입니다. `additional_data.name_match_score`에는 비교 대상 성명이 포함되지 않으며 ID와 점수만 포함되므로 경고 payload에 PII가 유입되지 않습니다.

각 문서에 서로 다른 문자 체계로 작성된 성명(예: 한 문서에는 히브리어, 다른 문서에는 라틴 문자)은 두 세션이 동일인에게 속한 경우에도 임계값 미만의 점수를 받을 수 있습니다. 이러한 특수한 경우, 두 세션의 신분증 문서가 다음 항목 모두에서 서로 일치하면 `DUPLICATED_FACE_NAME_MISMATCH`가 발생하지 않습니다:

* 두 문서의 발급 국가가 동일합니다.
* 두 문서 간에 식별자가 정확히 일치합니다. 문서 유형에 따라 동일한 국민 식별 번호가 두 필드 중 하나에 위치할 수 있으므로 `document_number`와 `personal_number`는 상호 호환되어 인정됩니다.
* 두 문서 모두에 생년월일이 기재되어 있는 경우 동일한 날짜여야 합니다.

성명이 동일한 문자 체계로 작성되었거나, 식별자 또는 발급 국가가 다르거나 누락된 경우, 또는 생년월일이 서로 일치하지 않는 경우에는 위에서 설명한 대로 경고가 계속 발생합니다.

### 패시브 라이브니스 품질(`method = "PASSIVE"`인 경우에만 해당)

| 위험 | 원인 | 심각도 | 해결 방법 |
| - | - | - | - |
| `MULTIPLE_FACES_DETECTED` | 캡처 중에 둘 이상의 얼굴이 감지되었습니다. 점수 산정 및 대조에는 항상 가장 큰 얼굴이 사용됩니다. | 설정 가능 — 기본값 `information` | 단독으로 다시 캡처하세요. |
| `LOW_FACE_QUALITY` | 얼굴 품질이 검토 임계값(기본값 15) 미만입니다. | `warning`; 거부 임계값(기본값 0 — 거부 비활성화됨) 미만인 경우 `error` | 초점 개선 / 가림 최소화 / 얼굴을 중앙에 맞춤. |
| `LOW_FACE_LUMINANCE` | 정규화된 조도가 최소 임계값(기본값 20) 미만입니다. | 설정 가능 — 기본값 `warning`(작업 기본값은 Review) | 조명 개선. |
| `HIGH_FACE_LUMINANCE` | 정규화된 조도가 최대 임계값(기본값 80)을 초과합니다. | 설정 가능 — 기본값 `warning`(작업 기본값은 Review) | 조명 줄이기; 역광 피하기. |

`LOW_FACE_LUMINANCE`와 `HIGH_FACE_LUMINANCE`는 상호 배타적입니다. 조도는 최소값 미만이거나 최대값 초과 중 하나이며, 둘 다 해당할 수는 없습니다.

### 연령 추정(어댑티브 워크플로 및 `AGE_ESTIMATION` 노드)

| 위험 | 원인 | 심각도 | 해결 방법 |
| - | - | - | - |
| `AGE_BELOW_MINIMUM` | 추정 연령이 설정된 최소 연령 미만임(또는 신분증 인증 대체가 활성화된 경우 경계 임계값 미만). | `error` | 설정된 경우 워크플로가 신분증 인증으로 대체됩니다. |
| `AGE_NOT_DETECTED` | 연령을 추정할 수 없으며 신분증 인증 대체가 비활성화되어 있습니다. | `error` | 대체를 활성화하거나 다시 캡처합니다. |

## 정확한 설명 문자열

API는 각 위험에 대해 다음과 같은 정확한 `short_description` 및 `long_description` 문자열을 반환합니다.

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `NO_FACE_DETECTED` | No Face Detected in liveness | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues. |
| `LIVENESS_FACE_ATTACK` | Liveness Face Attack | The system detected a potential attempt to bypass the liveness check. |
| `LOW_LIVENESS_SCORE` | Low liveness score | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. |
| `LIVENESS_VIDEO_ANOMALY` | Liveness video stream anomaly | The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live. |
| `FACE_IN_BLOCKLIST` | Face in blocklist | The system identified a face in the blocklist, which means the face is not allowed to be verified. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possible face in blocklist | The system identified a possible face in the blocklist, which means the face is not allowed to be verified. |
| `FACE_IN_ALLOWLIST` | Face in allowlist | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Possible face in allowlist | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal. |
| `DUPLICATED_FACE` | Duplicated face from other approved session | The system identified a duplicated face from another approved session, requiring further investigation. |
| `POSSIBLE_DUPLICATED_FACE` | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation. |
| `DUPLICATED_FACE_NAME_MISMATCH` | Duplicated face under a different name | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Face matches a liveness attack | The face in this liveness capture matches a face from an earlier session of this application whose own capture the liveness engine judged to be an attack with high confidence, in a session of another user. A genuine user can be rejected by mistake, so this is a signal for review, not proof of an attack. |
| `MULTIPLE_FACES_DETECTED` | Multiple faces detected | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review. |
| `LOW_FACE_QUALITY` | Low face quality | The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts. |
| `LOW_FACE_LUMINANCE` | Low face luminance | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended. |
| `HIGH_FACE_LUMINANCE` | High face luminance | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended. |
| `AGE_BELOW_MINIMUM` | Age below minimum | The age of the face is below the minimum age threshold for the application. |
| `AGE_NOT_DETECTED` | Age not detected | The system couldn't identify the age of the face, which is necessary for document verification. |

## 독립형 패시브 라이브니스 API

독립형 [Liveness API](https://docs.didit.me/ko/standalone-apis/passive-liveness.md)는 몇 가지 동작상의 차이점을 제외하고 동일한 위험 코드를 재사용합니다.

* `NO_FACE_DETECTED`와 `LOW_LIVENESS_SCORE`는 상호 배타적입니다. 점수 확인은 얼굴이 발견된 경우에만 실행됩니다. `LOW_LIVENESS_SCORE`는 요청의 `face_liveness_score_decline_threshold`(기본값 30)를 기준으로 발생하며 항상 `log_type: "error"`를 전달합니다.
* `POSSIBLE_FACE_IN_BLOCKLIST`는 검토 대신 거부(`log_type: "error"`)로 처리됩니다.
* `MULTIPLE_FACES_DETECTED`는 `log_type: "warning"`을 전달하는 반면, 중복 얼굴 위험은 정보 제공 수준으로 유지됩니다. `error` 수준의 경고만 독립형 응답의 `status`를 `Declined`로 전환합니다.
* 독립형 경고 항목에는 `feature`가 포함되지만 `node_id`는 포함되지 않습니다.

## 예시

### 공격 감지 시 자동 거부

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]
```

### 패시브 캡처 시 설정 가능한 경고

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.",
    "node_id": "liveness_primary"
  }
]
```

### payload를 포함한 중복 얼굴

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

여기서는 중복 얼굴 작업이 Review로 설정되어 있으므로 경고에 `log_type: "warning"`이 포함되고 라이브니스 보고서의 상태는 `In Review`가 됩니다. 기본값(No action)으로 설정된 경우 대신 `log_type: "information"`이 포함됩니다. 일치하는 얼굴이 독립형 API 호출이 아닌 워크플로 세션에서 비롯되었으므로 `api_service`는 `null`입니다.

### 다른 이름의 중복 얼굴

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE`는 자체 구성된 작업(여기서는 No action — `log_type: "information"`)을 유지하는 반면, `DUPLICATED_FACE_NAME_MISMATCH`는 기본값이 Review(`log_type: "warning"`)인 자체 작업을 수행합니다. 일반 중복 얼굴 설정 자체만으로는 플래그가 지정되지 않았더라도, 라이브니스 보고서의 상태는 둘 중 더 심각한 수준을 따르므로 여기서는 `In Review`가 됩니다.

### 측정값이 포함된 녹화 무결성 이상

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

이 예시는 움직이는 시퀀스의 사본 3개가 포함된 녹화본의 재생 증거를 보여줍니다. 구성된 작업이 `NO_ACTION`이므로 `log_type`은 `information`입니다. 간결성을 위해 이 예시에서 생략된 프레임 전송 진단은 해당 탐지 결과를 유발하지 않습니다.

## 경고 유형

각 위험에는 애플리케이션 설정에 따라 심각도가 할당됩니다. 세 가지 심각도는 다음과 같습니다.

## 관련 문서

* [라이브니스 보고서](https://docs.didit.me/ko/core-technology/liveness/report-liveness.md) — 전체 보고서 스키마 및 상태.
* [얼굴 대조 경고](https://docs.didit.me/ko/core-technology/face-match/warnings-face-match.md) — 함께 사용되는 1:1 얼굴 대조 경고.
* [webhook 이벤트](https://docs.didit.me/ko/integration/webhooks.md) — 라이브니스 단계가 완료되는 즉시 경고를 전달하는 `session.status.updated`.
* [데이터 모델 — 라이브니스 검사](https://docs.didit.me/ko/reference/data-models.md#라이브니스-검사) — 모든 필드가 포함된 표준 스키마.
* [데이터 모델 — 경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) — `warnings[]` 내 모든 항목의 구조.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.