> ## 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의 1:1 얼굴 대조 모듈에서 발생하는 낮은 유사도, 누락된 참조 이미지, 재시도 횟수 초과 등 모든 경고의 원인, 심각도 및 해결 방법을 제공합니다.

## 개요

얼굴 대조 보고서의 경고는 Didit이 1:1 얼굴 비교를 실행하는 동안 관찰한 모든 조건을 표시합니다. 경고는 `face_matches[]`의 각 항목에 있는 `warnings[]` 배열에 포함됩니다([얼굴 대조 보고서](https://docs.didit.me/ko/core-technology/face-match/report-face-match.md) 참조). 각 항목에는 `feature: "FACEMATCH"` 및 이를 발생시킨 워크플로 노드의 `node_id`도 함께 포함됩니다.

모든 경고에는 세 가지 레이어가 있습니다.

1. **`risk` 코드** — 코드에서 매칭할 수 있는 안정적인 식별자입니다.
2. **`log_type`** — 워크플로의 유사도 점수 임계값에서 파생되는 `information`, `warning` 또는 `error`입니다.
3. **결정 영향** — 유사도 점수에 대한 워크플로의 검토 및 거부 임계값에 의해 설정됩니다.

얼굴 대조 모듈은 의도적으로 단순하게 구성되어 있으며, 아래에 전체 목록으로 안내된 정확히 5개의 위험 코드가 있습니다.

## 자동 거부 조건

다음 위험은 얼굴 대조 보고서(및 세션)를 항상 `Declined` 상태로 만듭니다.

| Risk | 트리거 |
| - | - |
| `NO_REFERENCE_IMAGE` | `source_image`(기준 이미지) 또는 `target_image`(셀피) 중 하나가 누락되어 비교가 불가능했습니다. |

`NO_REFERENCE_IMAGE`가 발생하면 `LOW_FACE_MATCH_SIMILARITY`는 억제됩니다(점수를 산정할 대상이 없기 때문입니다).

단 한 가지 예외가 있습니다.
신분증 확인 단계가 인물 사진을 반환하지 않고 얼굴을 확인하지 않는 [비서류 조회](https://docs.didit.me/ko/core-technology/id-verification/non-doc-lookup.md)로 완료된 경우, 얼굴 대조는 설계상 실시간 캡처와 비교할 대상이 없습니다.
이 경우 자동 거부가 아닌 `null` 점수와 함께 `FACE_MATCH_NOT_COMPUTED`로 보고되며, 아래의 `face_match_not_computed_action`에 의해 결정됩니다.

## 구성 가능한 인증 설정

Didit 콘솔에서 얼굴 대조 유사도 점수는 두 가지 임계값으로 관리됩니다(Approve/Review/Decline 토글 없음).

| 설정 | 기본값 | 동작 |
| - | - | - |
| `face_match_score_review_threshold` | 70 | `score` ≤ 이 값일 때 `LOW_FACE_MATCH_SIMILARITY`가 발생하고 상태가 `In Review`로 이동합니다. |
| `face_match_score_decline_threshold` | 50 | `score` ≤ 이 값일 때 동일한 경고가 `error`로 격상되며 상태가 `Declined`로 이동합니다. |

오승인이 너무 많이 발생하는 경우 검토 임계값을 더 높게 조정하고, 오거부가 너무 많이 발생하는 경우 거부 임계값을 더 낮게 조정하십시오.

별도의 설정으로 유사도 점수를 **전혀 계산할 수 없을 때**(이미지 중 하나에서 얼굴이 감지되지 않았거나 비서류 조회로 비교할 기준 이미지가 남지 않은 경우) 발생하는 동작을 제어합니다.

| 설정 | 기본값 | 동작 |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | "계산할 수 없음" 결과가 최종 확정되었을 때 적용되는 작업입니다. `REVIEW`는 보고서를 `In Review`로 전송하고, `DECLINE`은 `Declined`로 설정합니다. (자동 승인 옵션은 없습니다. 계산되지 않은 점수는 절대 묵인되어 통과되지 않습니다.) |

이 작업은 `FACE_MATCH_NOT_COMPUTED`(문서 인물 사진에 얼굴이 없거나 비서류 조회 후 기준 이미지가 전혀 없음) 및 시도 횟수를 모두 소진한 `NO_FACE_IN_SELFIE`(사용자의 재시도 후에도 셀피에서 얼굴이 감지되지 않음)를 제어합니다. 셀피에 문제가 있는 경우 사용자는 먼저 다시 촬영하도록 요청받으며(아래 참조), 시도 가능 횟수를 모두 소진한 후에도 얼굴을 감지할 수 없는 경우에만 이 작업이 적용됩니다.

유사도가 낮은 실패 역시 상태가 최종 확정되기 전에 캡처 재시도 루프에 진입합니다. 사용자에게 재촬영을 포함해 총 `face_match_max_attempts`회의 시도가 주어집니다(기본값 3, 워크플로 노드당 2\~5회 구성 가능). 더 선명한 셀피를 다시 촬영하여 문제를 해결할 수 있으므로 `NO_FACE_IN_SELFIE` 실패도 동일한 재시도 루프를 사용합니다. `FACE_MATCH_NOT_COMPUTED` 실패는 재시도되지 **않습니다**. 이 단계에서는 신분증 문서 인물 사진을 다시 촬영할 수 없기 때문입니다. 시도 횟수를 모두 소진한 경우에만 마지막 시도의 상태가 적용되며, 이를 기록하기 위해 `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`가 로깅됩니다.

독립형 [얼굴 대조 API](https://docs.didit.me/ko/standalone-apis/face-match.md)에는 거부 임계값(`face_match_score_decline_threshold` 요청 옵션, 기본값 30)만 존재합니다. 발생한 모든 경고는 요청을 거부하며, 얼굴을 전혀 비교할 수 없을 때 `NO_REFERENCE_IMAGE`가 발생합니다.

## 생성되는 경고

| 위험 | 원인 | 심각도 | 상태 영향 여부 | 해결 방법 |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. `NO_REFERENCE_IMAGE`도 함께 존재하는 경우 억제됩니다. | 임계값 사이인 경우 `warning`, 거부 임계값 이하인 경우 `error` | 임계값 사이인 경우 `In Review`, 거부 임계값 이하인 경우 `Declined` | 임계값을 조정하거나 수동 검토를 통해 승인합니다. |
| `FACE_MATCH_NOT_COMPUTED` | **신분증 사진**에서 얼굴이 감지되지 않았거나, 신분증 인증 단계가 비교할 참조 이미지를 남기지 않는 [비문서 조회](https://docs.didit.me/ko/core-technology/id-verification/non-doc-lookup.md)(사진을 반환하지 않고 얼굴을 확인하지 않는 레지스터)였기 때문에 유사도 점수를 계산할 수 없습니다. `NO_REFERENCE_IMAGE`도 함께 존재하는 경우 억제됩니다. | `face_match_not_computed_action`이 `REVIEW`인 경우 `warning`, `DECLINE`인 경우 `error` | `face_match_not_computed_action`에 따라 `In Review` 또는 `Declined` | 이 단계에서는 신분증 이미지를 다시 캡처할 수 없습니다. 수동 검토를 통해 해결하거나 워크플로 앞 단계에서 신분증을 다시 캡처하도록 합니다. 데이터 전용 조회를 거친 후에는 `face_match_not_computed_action`을 원하는 결과로 설정하거나, 생체 대조가 중요한 국가에서는 신분증 제출을 필수로 요구하도록 설정하세요. |
| `NO_FACE_IN_SELFIE` | 사용자의 **셀피**에서 얼굴이 감지되지 않아 유사도 점수를 계산할 수 없습니다. 이 경고가 확정되기 전에 사용자에게 셀피를 다시 촬영하도록 요청합니다. | `face_match_not_computed_action`이 `REVIEW`인 경우 `warning`, `DECLINE`인 경우 `error` | 재시도 횟수를 모두 소진한 후, `face_match_not_computed_action`에 따라 `In Review` 또는 `Declined` | 사용자가 조명이 밝고 선명한 정면 셀피를 다시 촬영합니다. |
| `NO_REFERENCE_IMAGE` | 참조 이미지 또는 대상 이미지가 누락되었습니다(비문서 조회에서 생성되지 않은 참조 이미지는 제외되며, 이는 `FACE_MATCH_NOT_COMPUTED`에 해당). | `error` | **자동 거부** | 신분증 사진과 라이브니스 셀피가 모두 캡처되었는지 확인하세요. 독립 실행형 API의 경우 유효한 얼굴 이미지 두 개를 전달해야 합니다. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | 유사도 부족 실패가 반복된 후 사용자가 캡처 재시도 한도(`face_match_max_attempts`)를 모두 소진했습니다. | `information` | 없음 — 마지막 시도의 계산된 상태(거부 또는 검토)가 적용되었음을 기록합니다. | 워크플로 노드에서 `face_match_max_attempts` 값을 늘리거나 수동 검토를 통해 해결합니다. |

## 예시

### 검토 중 — 경계선 수준의 유사도

```json theme={null}
"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_1"
  }
]
```

### 검토 중 — 얼굴 대조를 계산할 수 없음

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### 자동 거부 — 참조 이미지 누락

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]
```

### 재시도 횟수 소진 — 마지막 시도의 상태 적용

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "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_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]
```

> [!NOTE]
>
> 독립형 [Face Match API](https://docs.didit.me/ko/standalone-apis/face-match.md)는 `node_id`를 제외하고 동일한 경고 형식을 반환합니다(비교 작업이 워크플로 노드에 바인딩되지 않음).

## 경고 유형

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

## 관련 문서

* [얼굴 대조 보고서](https://docs.didit.me/ko/core-technology/face-match/report-face-match.md) — 전체 보고서 스키마 및 상태.
* [라이브니스 경고](https://docs.didit.me/ko/core-technology/liveness/warnings-liveness.md) — 셀피 캡처 시 발생하는 업스트림 경고.
* [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.