> ## 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.

# 얼굴 검색 1:N 경고 및 오류 코드

> Didit의 얼굴 검색 1:N 경고 코드 설명: 차단 목록 일치, 중복 얼굴, 다중 얼굴 감지 및 얼굴이 감지되지 않은 이미지를 거부하는 처리 기준.

## 개요

얼굴 검색은 팀에서 검색 결과가 `Approved` 또는 `Declined`로 반환된 **이유**를 파악할 수 있도록 몇 가지 경고를 생성합니다. 경고는 `POST /v3/face-search/` 응답의 `face_search.warnings[]` 배열로 반환됩니다([얼굴 검색 보고서](https://docs.didit.me/ko/core-technology/face-search/report-face-search.md) 참조).

이곳의 경고는 워크플로 경고에 비해 **축소된 형태**를 사용합니다. 즉, `node_id`가 없습니다. 문서화된 응답 명세는 `risk`, `additional_data`, `log_type`, `short_description`, `long_description`의 5개 필드를 선언하며, 런타임 payload에는 추가로 `feature`가 포함되는데 이 endpoint에서는 항상 `"LIVENESS"`입니다.

## 생성되는 경고

| 위험 | 원인 | 심각도 (`log_type`) | 상태에 미치는 영향 | 권장 조치 사항 |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | 검색 이미지가 애플리케이션의 얼굴 차단 목록에 있는 얼굴과 높은 신뢰도 유사도 구간 이상으로 일치했습니다. | `error` | `Declined`를 강제합니다. | 사용자를 거부합니다. `additional_data.blocklisted_session_id`를 통해 연결된 세션을 조사합니다. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 차단 목록에 등록된 얼굴이 높은 신뢰도 구간 아래의 더 낮은 "가능" 유사도 구간 내에서 일치했습니다. | `error` | 독립형 얼굴 검색 API에서 `Declined`를 강제합니다(이 위험을 검토로 보내는 워크플로 라이브니스 확인보다 엄격함). | 수동으로 검토합니다. 조치를 취하기 전에 원본 차단 목록 증거와 일치 항목을 확인합니다. |
| `MULTIPLE_FACES_DETECTED` | 제출된 검색 이미지에서 둘 이상의 얼굴이 감지되었습니다. 감지된 가장 큰 얼굴을 사용하여 검색은 계속 실행됩니다. | `warning` | 없음 — 단독으로 거부되지 않습니다. | 가장 큰 얼굴이 의도한 대상이 아닌 경우 프레임에 단일 피사체만 두고 다시 캡처합니다. |
| `DUPLICATED_FACE` | 얼굴이 높은 신뢰도 구간 이상에서 **승인됨** 세션의 얼굴 또는 가져온 사용자 프로필 얼굴과 일치했습니다. 독립형 endpoint는 동일한 `vendor_data` 세션을 제외하지 않으므로, 재방문 사용자는 자신의 이전 세션과 일치하게 됩니다. | `information` | 없음 — 중복은 거부가 아닌 신호로 표시됩니다. | `additional_data.duplicated_session_id`를 통해 연결된 세션을 조사합니다. 자체적으로 계정을 차단할지 또는 병합할지 결정합니다. |
| `POSSIBLE_DUPLICATED_FACE` | `DUPLICATED_FACE`와 동일하지만 유사도가 높은 신뢰도 구간이 아닌 더 낮은 "가능" 구간에 속합니다. | `information` | 없음. | 두 기록을 동일인으로 처리하기 전에 수동 검토를 진행합니다. |

생성자: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); 상태 도출: `get_face_search_status` (`apis/views/face_search.py:242-248`), 이는 두 가지 차단 목록 위험에 대해서**만** 거부합니다.

알아두어야 할 생성 규칙:

* **차단 목록이 중복보다 우선합니다.** 확인된 차단 목록 일치는 `DUPLICATED_FACE`를 억제하고, 가능한 차단 목록 일치는 `POSSIBLE_DUPLICATED_FACE`를 억제합니다. 즉, 동일한 신뢰도 구간에 대해 한 쌍의 두 구성원을 모두 받는 일은 없습니다.
* **`additional_data`는 일치하는 첫 번째 얼굴만 참조합니다**(`matches[]`에 여러 개가 포함되어 있더라도 마찬가지입니다). 차단 목록 경고에는 `{blocklisted_session_id, blocklisted_session_number, api_service}`가 포함되고, 중복 경고에는 `{duplicated_session_id, duplicated_session_number, api_service}`가 포함되며, `MULTIPLE_FACES_DETECTED`에는 `null`이 포함됩니다. `api_service` 값은 대문자(예: `PASSIVE_LIVENESS`)이거나 워크플로 세션의 경우 `null`입니다.
* **허용 목록에 있는 얼굴은 중복 경고를 억제합니다** — 높은 신뢰도의 허용 목록 일치는 `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE`를 제거합니다(차단 목록 경고는 절대 제거하지 않습니다).

### 정확한 경고 문자열

| 위험 | `short_description` | `long_description` |
| - | - | - |
| `FACE_IN_BLOCKLIST` | 차단 목록에 있는 얼굴 | 시스템이 차단 목록에서 얼굴을 식별했으며, 이는 해당 얼굴의 인증이 허용되지 않음을 의미합니다. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | 차단 목록에 있을 가능성이 있는 얼굴 | 시스템이 차단 목록에 있을 가능성이 있는 얼굴을 식별했으며, 이는 해당 얼굴의 인증이 허용되지 않음을 의미합니다. |
| `DUPLICATED_FACE` | 다른 승인된 세션의 중복된 얼굴 | 시스템이 다른 승인된 세션에서 중복된 얼굴을 식별하여 추가 조사가 필요합니다. |
| `POSSIBLE_DUPLICATED_FACE` | 다른 승인된 세션의 중복 가능성이 있는 얼굴 | 시스템이 다른 승인된 세션에서 중복 가능성이 있는 얼굴을 식별하여 추가 조사가 필요합니다. |
| `MULTIPLE_FACES_DETECTED` | 여러 얼굴 감지됨 | 라이브니스 이미지에서 여러 얼굴이 감지되었습니다. 시스템은 라이브니스 검증과 얼굴 대조에 가장 큰 얼굴을 사용하지만, 여러 얼굴이 존재할 경우 추가 검토가 필요할 수 있습니다. |

### 검색 이미지 게이트

`user_image`에서 얼굴이 감지되지 않으면 API는 `face_search` 객체가 생성되기 **전에** HTTP `400` 및 `{"error": "No face detected in the image"}`로 요청을 거부합니다. 따라서 성공한 얼굴 검색 응답에는 `NO_FACE_DETECTED` 경고가 절대 나타나지 않습니다. 이는 `warnings[]`가 아닌 최상위 `error` 문자열로 반환됩니다.

## 구성 가능한 설정

확인된 일치 항목(`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`)과 가능한 일치 항목(`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`)을 구분하는 유사도 구간은 내부적으로 고정되어 있습니다. 애플리케이션별 임계값 조정은 이 endpoint가 아닌 워크플로 라이브니스 확인에 적용됩니다. 요청별로 제어할 수 있는 스위치는 다음과 같습니다.

* **`search_type`** (`most_similar`, 기본값 | `blocklisted_or_approved`) — `most_similar`는 등록된 모든 얼굴을 유사도순으로 순위를 매깁니다. `blocklisted_or_approved`는 후보를 차단 목록에 등록된 얼굴, 허용 목록에 등록된 얼굴, 승인된 세션의 얼굴, 가져온 사용자 프로필 얼굴로 제한하며 차단 목록 항목의 순위를 먼저 매깁니다.
* **`save_api_request`** (기본값 `true`) — 호출을 API 유형 세션으로 저장하고 검색된 얼굴을 얼굴 검색 색인에 등록합니다. 얼굴 검색 호출로 등록된 얼굴은 향후 얼굴 검색 결과에서 제외됩니다. 저장하거나 등록하지 않고 조회하려면 `false`로 설정합니다.
* **`rotate_image`** (기본값 `false`) — 90도 회전을 시도하고 얼굴 감지가 가장 잘 된 방향을 유지합니다. EXIF 방향 정보가 누락되었을 때 유용합니다.

## 예시

### 차단 목록 일치 (`Declined`로 강제 설정됨)

```json theme={null}
{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}
```

### 중복 신호 (상태는 `Approved`로 유지됨)

```json theme={null}
{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "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."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "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."
    }
  ]
}
```

## 관련 항목

* [Face Search 보고서](https://docs.didit.me/ko/core-technology/face-search/report-face-search.md) — 전체 응답 형태
* [Face Search API 참조](https://docs.didit.me/ko/standalone-apis/face-search.md) — 요청 파라미터
* [Face Match 경고](https://docs.didit.me/ko/core-technology/id-verification/warnings-id-verification.md) — 셀피와 문서 간 1:1 대조 경고(Face Search와 별개)
* [데이터 모델 — Face Search](https://docs.didit.me/ko/reference/data-models.md#얼굴-검색) — 표준 스키마

### 경고 유형


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