> ## 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/ja/core-technology/face-search/report-face-search.md)を参照）。

ここでの警告は、ワークフローの警告と比べて**簡略化された構造**で、`node_id`はありません。ドキュメント化されたレスポンス仕様では5つのフィールド（`risk`、`additional_data`、`log_type`、`short_description`、`long_description`）が宣言されており、実行時のペイロードにはさらに`feature`が含まれます。このエンドポイントでは、この値は常に`"LIVENESS"`です。

## 生成される警告

| リスク | 原因 | 重大度（`log_type`） | ステータスへの影響 | 推奨される対処 |
| - | - | - | - | - |
| `FACE_IN_BLOCKLIST` | 検索画像が、高信頼度の類似度帯を超えて、アプリケーションの顔ブロックリスト内の顔と一致しました。 | `error` | `Declined`を強制します。 | ユーザーを拒否します。`additional_data.blocklisted_session_id`で紐づくセッションを調査してください。 |
| `POSSIBLE_FACE_IN_BLOCKLIST` | ブロックリストに登録された顔が、高信頼度帯より下の「可能性あり」の類似度帯で一致しました。 | `error` | スタンドアロンの顔検索APIでは`Declined`を強制します（このリスクをレビューに回すワークフローのライブネスチェックより厳格です）。 | 手動レビュー。対応する前に、元のブロックリストの証拠と照らし合わせて一致を確認してください。 |
| `MULTIPLE_FACES_DETECTED` | 送信された検索画像から複数の顔が見つかりました。検索は、検出された最も大きい顔を使って引き続き実行されます。 | `warning` | なし。この警告単独で却下になることはありません。 | 最も大きい顔が意図した人物でない場合は、1人だけがフレームに入った状態で再撮影してください。 |
| `DUPLICATED_FACE` | 顔が、高信頼度帯を超えて、**承認済み**セッションの顔、またはインポートされたユーザープロファイルの顔と一致しました。スタンドアロンのエンドポイントは同じ`vendor_data`のセッションを除外しないため、再訪したユーザーは自身の過去のセッションと一致します。 | `information` | なし。重複は却下ではなくシグナルとして提示されます。 | `additional_data.duplicated_session_id`で紐づくセッションを調査してください。アカウントをブロックするか統合するかは、貴社側で判断してください。 |
| `POSSIBLE_DUPLICATED_FACE` | `DUPLICATED_FACE`と同じですが、類似度が高信頼度帯ではなく、その下の「可能性あり」の帯にあります。 | `information` | なし。 | 2つのレコードを同一人物として扱う前に、手動レビューを行ってください。 |

生成元は`FaceSearchAPIView.add_warnings`（`apis/views/face_search.py:250-330`）、ステータスの導出は`get_face_search_status`（`apis/views/face_search.py:242-248`）で、後者は2つのブロックリストのリスクの場合**のみ**却下します。

知っておくべき生成ルール：

* **ブロックリストは重複より優先されます。** 確定したブロックリスト一致は`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` | ブロックリスト内の顔 | 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. |
| `DUPLICATED_FACE` | 他の承認済みセッションとの重複顔 | 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. |
| `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. |

### 検索画像のチェック

`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`）を分ける類似度の範囲は内部で固定されています。アプリケーションごとのしきい値調整はワークフローのライブネスチェックに適用され、このエンドポイントには適用されません。リクエストごとに制御できるスイッチは次のとおりです。

* **`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."
    }
  ]
}
```

## 関連情報

* [顔検索レポート](https://docs.didit.me/ja/core-technology/face-search/report-face-search.md)：レスポンスの全体構造
* [顔検索APIリファレンス](https://docs.didit.me/ja/standalone-apis/face-search.md)：リクエストパラメーター
* [顔照合の警告](https://docs.didit.me/ja/core-technology/id-verification/warnings-id-verification.md)：セルフィーと書類の1:1照合に関する警告（顔検索とは別）
* [データモデル：顔検索](https://docs.didit.me/ja/reference/data-models.md#顔検索)：正規スキーマ

### 警告の種類


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