> ## 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 생체 인증 경고(LOW_LIVENESS_SCORE, 얼굴 공격, 차단 목록 일치 등)를 처리하고 임계값 및 거부 작업을 설정하는 방법을 확인하세요.

생체 인증은 라이브니스 검사와 세션 생성 시 확인된 기준 얼굴(제공된 `portrait_image` 또는 `vendor_data`로 조회된 사용자의 저장된 얼굴)과의 선택적 1:1 얼굴 대조를 결합합니다. 각 단계는 V3 결정 payload에 고유한 경고를 생성합니다. 이 페이지에서는 모든 코드, 표시 위치, 임계값이 최종 세션 상태로 변환되는 방식을 설명합니다.

## 개요

생체 인증 세션이 실행되면 Didit은 다음을 수행합니다.

* 3D Action, Flash 또는 Passive Liveness(`method`: `ACTIVE_3D`, `FLASHING` 또는 `PASSIVE`)를 사용하여 라이브 셀피를 캡처합니다.
* 캡처된 이미지에서 가장 큰 얼굴을 추출하고 라이브니스 점수를 산정합니다.
* 워크플로에 얼굴 대조가 포함된 경우, 캡처된 얼굴을 세션의 기준 얼굴(제공된 `portrait_image` 또는 사용자의 저장된 얼굴)과 비교합니다.
* 각 단계의 결과와 모든 경고를 세션 결정에 기록합니다.

경고는 플랫폼 전반에서 사용되는 공통 [경고 객체](https://docs.didit.me/ko/reference/data-models.md#경고-객체) 형태를 유지합니다: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

## 경고 표시 위치

| 결정 응답 키 | 경고의 기능 태그 | 발생 조건 |
| - | - | - |
| `liveness_checks[].warnings[]` | `LIVENESS` | 라이브니스 점수 산정, 얼굴 품질, 휘도, 다중 얼굴 감지, 차단 목록/허용 목록/중복 얼굴 검사 시. |
| `face_matches[].warnings[]` | `FACEMATCH` | 세션의 기준 얼굴(제공된 `portrait_image` 또는 사용자의 저장된 얼굴)을 대상으로 한 얼굴 대조 시. |

일반적인 생체 인증 세션에서는 각 배열에 하나의 항목이 포함됩니다. 다중 인스턴스 워크플로에서는 각 경고의 `node_id`를 통해 해당 경고를 생성한 단계를 구분할 수 있습니다.

## 자동 거부 조건

다음 경고는 워크플로 구성 방식과 관계없이 항상 해당 단계를 거부(`log_type: "error"`)합니다.

| 위험 | 기능 | 자동 거부 이유 |
| - | - | - |
| `FACE_IN_BLOCKLIST` | `LIVENESS` | 얼굴이 얼굴 차단 목록의 항목과 일치합니다. |
| `NO_FACE_DETECTED` | `LIVENESS` | 라이브니스 캡처 중 얼굴이 감지되지 않았거나, 사용자가 캡처 재시도 횟수를 모두 소진했습니다. |
| `LIVENESS_FACE_ATTACK` | `LIVENESS` | 프레젠테이션 공격(가면, 화면 재생, 딥페이크 계열 스푸핑)이 감지되었습니다. |
| `NO_REFERENCE_IMAGE` | `FACEMATCH` | 비교를 수행할 기준 이미지가 없습니다. 이 경고가 발생하면 `LOW_FACE_MATCH_SIMILARITY`는 생략됩니다. |

`NO_FACE_DETECTED`가 발생하면 점수를 산정할 얼굴이 없으므로 `LOW_LIVENESS_SCORE`는 생략됩니다.

## 설정 가능한 임계값 및 작업

이러한 경고는 점수가 산정된 후 각 워크플로에 설정한 임계값 및 작업을 통해 상태로 매핑됩니다.

| 위험 | 기능 | 설정 가능한 동작 |
| - | - | - |
| `LOW_LIVENESS_SCORE` | `LIVENESS` | 점수가 검토 임계값 이하인 경우 → `In Review`, 거부 임계값 이하인 경우 → `Declined`. |
| `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | 점수가 검토 임계값(기본값 70) 이하인 경우 → `In Review`, 거부 임계값(기본값 50) 이하인 경우 → `Declined`. |
| `LOW_FACE_QUALITY` | `LIVENESS` | 검토 임계값(기본값 15) → `In Review`, 거부 임계값(기본값 0, 즉 거부 비활성화) → `Declined`. Passive Liveness 전용. |
| `LOW_FACE_LUMINANCE` | `LIVENESS` | 최소 휘도 임계값(기본값 20) 미만: 작업 없음 / 검토(기본값) / 거부. Passive Liveness 전용. |
| `HIGH_FACE_LUMINANCE` | `LIVENESS` | 최대 휘도 임계값(기본값 80) 초과: 작업 없음 / 검토(기본값) / 거부. Passive Liveness 전용. |
| `MULTIPLE_FACES_DETECTED` | `LIVENESS` | 둘 이상의 얼굴이 캡처된 경우: 작업 없음(기본값) / 검토 / 거부. Passive Liveness 전용. |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | 두 경고에 공통으로 적용되는 중복 얼굴 작업: 다른 사용자의 승인되었거나 가져온 얼굴과 일치하는 경우 작업 없음(기본값) / 검토 / 거부. |
| `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | 별도 작업(`face_liveness_duplicated_face_name_mismatch_action`): 작업 없음 / 검토(기본값) / 거부. 일치하는 세션의 신원이 이 세션에서 확인된 이름과 일치하지 않을 때 `DUPLICATED_FACE`와 함께 생성됩니다. 자세한 내용은 [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md#세션-간-얼굴-대조)를 참고하세요. |

`POSSIBLE_FACE_IN_BLOCKLIST`(`LIVENESS`)는 설정할 수 **없습니다**. 신뢰도가 낮은 차단 목록 일치는 항상 검토(`log_type: "warning"`)로 라우팅됩니다.

## 캡처 재시도

해결 가능한 캡처 품질 위험(낮은 점수, 얼굴 미감지, 품질, 휘도, 다중 얼굴, 그리고 얼굴 대조 시 낮은 유사도)으로만 인한 실패는 상태가 확정되기 전에 재시도 루프로 들어갑니다. 사용자는 `face_liveness_max_attempts` / `face_match_max_attempts`에 설정된 횟수만큼, 최대 총 시도 횟수(기본값 3회, 워크플로 노드당 2\~5회 구성 가능)까지 시도할 수 있습니다. 시도 횟수가 모두 소진되면 마지막 시도에서 계산된 상태가 적용되며, 이를 기록하기 위해 `LIVENESS_MAX_ATTEMPTS_EXCEEDED` 또는 `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`가 `information`으로 로깅됩니다.

## 라이브니스 경고

API는 다음과 같은 정확한 `short_description` 및 `long_description` 문자열을 반환합니다.

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_LIVENESS_SCORE` | 낮은 라이브니스 점수 | 라이브니스 검사 결과 점수가 낮게 나왔으며, 이는 실제 얼굴이 아닌 표현물을 사용했거나 생체 인식 데이터의 품질이 낮을 가능성을 나타냅니다. |
| `NO_FACE_DETECTED` | 라이브니스에서 얼굴 미감지 | 시스템이 라이브니스 검사 중 얼굴을 식별하지 못했습니다. 이는 이미지 품질 저하, 부적절한 위치 지정 또는 기술적 문제로 인한 것일 수 있습니다. |
| `LIVENESS_FACE_ATTACK` | 라이브니스 얼굴 공격 | 시스템이 라이브니스 검사를 우회하려는 잠재적 시도를 감지했습니다. |
| `FACE_IN_BLOCKLIST` | 차단 목록에 포함된 얼굴 | 시스템이 차단 목록에서 얼굴을 식별했습니다. 즉, 해당 얼굴은 인증이 허용되지 않습니다. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 차단 목록에 포함되었을 가능성이 있는 얼굴 | 시스템이 차단 목록에 포함되었을 가능성이 있는 얼굴을 식별했습니다. 즉, 해당 얼굴은 인증이 허용되지 않습니다. |
| `FACE_IN_ALLOWLIST` | 허용 목록에 포함된 얼굴 | 해당 얼굴이 애플리케이션의 얼굴 허용 목록과 일치하여 이 신호에 대한 중복 얼굴 작업이 건너뛰어졌습니다. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | 허용 목록에 포함되었을 가능성이 있는 얼굴 | 해당 얼굴이 애플리케이션의 얼굴 허용 목록과 일치했을 가능성이 있어 이 신호에 대한 중복 얼굴 가능성 관련 작업이 건너뛰어졌습니다. |
| `DUPLICATED_FACE` | 승인된 다른 세션의 중복 얼굴 | 시스템이 승인된 다른 세션에서 중복된 얼굴을 식별하여 추가 조사가 필요합니다. |
| `POSSIBLE_DUPLICATED_FACE` | 승인된 다른 세션의 중복 가능성이 있는 얼굴 | 시스템이 승인된 다른 세션에서 중복 가능성이 있는 얼굴을 식별하여 추가 조사가 필요합니다. |
| `DUPLICATED_FACE_NAME_MISMATCH` | 다른 이름으로 중복된 얼굴 | 동일한 얼굴이 이미 다른 세션에서 승인되었으나 다른 이름으로 등록되어 있습니다. 중복된 대상의 신원이 본 세션에 신고된 신원과 일치하지 않으며, 이는 신원 사기의 강력한 지표입니다. |
| `MULTIPLE_FACES_DETECTED` *(패시브 전용)* | 여러 얼굴 감지됨 | 라이브니스 이미지에서 여러 얼굴이 감지되었습니다. 시스템은 라이브니스 검증 및 얼굴 비교에 가장 큰 얼굴을 사용하지만, 여러 얼굴이 존재하면 추가 검토가 필요할 수 있습니다. |
| `LOW_FACE_QUALITY` *(패시브 전용)* | 낮은 얼굴 품질 | 얼굴 이미지 품질이 허용 임계값 미만이어서 라이브니스 감지의 신뢰도에 영향을 미칠 수 있습니다. 이는 카메라 해상도, 초점 또는 압축 왜곡 때문일 수 있습니다. |
| `LOW_FACE_LUMINANCE` *(패시브 전용)* | 낮은 얼굴 밝기 | 얼굴 이미지가 너무 어두워 라이브니스 감지의 정확도에 영향을 미칠 수 있습니다. 더 나은 조명 환경을 권장합니다. |
| `HIGH_FACE_LUMINANCE` *(패시브 전용)* | 높은 얼굴 밝기 | 얼굴 이미지가 너무 밝거나 과다 노출되어 라이브니스 감지의 정확도에 영향을 미칠 수 있습니다. 조명을 줄이거나 직접 조명을 피하는 것을 권장합니다. |
| `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | 최대 라이브니스 시도 횟수 초과 | 라이브니스 캡처 최대 시도 횟수에 도달했습니다. 마지막 시도의 계산된 상태(거부 또는 검토)가 적용되었습니다. |

차단 목록, 허용 목록 및 중복 일치 항목에는 일치하는 세션 정보(`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, 일치하는 `*_session_number` 및 `api_service`)가 포함된 `additional_data`가 전달됩니다. 보고서당 이 6개 코드 중 하나만 표시됩니다. `DUPLICATED_FACE_NAME_MISMATCH`는 예외입니다. 일치하는 세션의 신원이 본 세션의 확인된 이름과 일치하지 않을 때, `DUPLICATED_FACE`를 대체하지 않고 **추가로** 생성됩니다. 이 코드의 `additional_data`에는 동일한 중복 세션 필드에 `name_match_score`가 추가됩니다. 양쪽 세션의 신분증 문서가 발급 국가, 정확한 문서 번호 또는 개인 식별 번호, 모순되지 않는 생년월일을 공유하는 경우 서로 다른 문자 체계로 표기된 이름은 불일치로 처리되지 않습니다. [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md#세션-간-얼굴-대조)를 참고하십시오.

## 얼굴 대조 경고

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | 낮은 얼굴 대조 유사도 | 제공된 이미지의 얼굴 특징이 기준 이미지와 밀접하게 일치하지 않아 신원이 일치하지 않을 가능성을 나타냅니다. |
| `NO_REFERENCE_IMAGE` | 얼굴 대조를 수행할 소스 이미지를 찾을 수 없음 | 얼굴 비교를 위한 기준 이미지가 누락되어 시스템이 얼굴 대조 프로세스를 완료할 수 없습니다. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | 최대 얼굴 대조 시도 횟수 초과 | 얼굴 대조 캡처 최대 시도 횟수에 도달했습니다. 마지막 시도의 계산된 상태(거부 또는 검토)가 적용되었습니다. |

## 예시 — 얼굴 공격으로 거부됨

```json theme={null}
{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": 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": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}
```

## 예시 — 낮은 유사도로 검토 중

```json theme={null}
{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}
```

점수(58.70)가 거부 임계값(기본값 50)과 검토 임계값(기본값 70) 사이에 위치하므로 경고에 `log_type: "warning"`이 포함되고 얼굴 대조 상태는 `In Review`가 됩니다. 이 예시에서 경고는 `session_id`가 `11111111-2222-3333-4444-555555555555`인 세션에서 발생했습니다. 기준 이미지가 세션 생성 시 저장된 인물 사진에서 가져온 것이므로 `source_image_session_id`에는 해당 세션 자체의 id가 전달됩니다.

## 경고 유형

애플리케이션 설정에 따라 각 위험에 경고 유형이 할당됩니다. 경고는 세 가지 심각도 카테고리로 나뉩니다.

## 관련 항목

> [card] [생체 인증 보고서](https://docs.didit.me/ko/core-technology/biometric-auth/report-biometric-authentication.md)
>
> V3 결정에서 `liveness_checks[]` 및 `face_matches[]`가 표시되는 위치입니다.

> [card] [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md)
>
> 중복 얼굴 일치를 포함한 전체 라이브니스 경고 레퍼런스입니다.

> [card] [얼굴 대조 경고](https://docs.didit.me/ko/core-technology/face-match/warnings-face-match.md)
>
> 1:1 비교를 위한 전체 얼굴 대조 경고 레퍼런스입니다.


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