顔検索（1:N）の警告とエラーコード

概要

顔検索は少数の警告を出力し、検索がApprovedまたはDeclinedを返した理由をチームが把握できるようにします。警告はPOST /v3/face-search/レスポンスのface_search.warnings[]配列で返されます（顔検索レポートを参照）。ここでの警告は、ワークフローの警告と比べて簡略化された構造で、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`を強制)

{
  "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`のまま)

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

認証

検証

モニタリング

プラットフォーム

顔検索（1:N）の警告とエラーコード

概要

生成される警告

警告文字列の正確な内容

検索画像のチェック

設定可能な項目

例

ブロックリスト一致 (`Declined`を強制)

重複シグナル (ステータスは`Approved`のまま)

関連情報

警告の種類

​概要

​生成される警告

​警告文字列の正確な内容

​検索画像のチェック

​設定可能な項目

​例

​ブロックリスト一致 (Declinedを強制)

​重複シグナル (ステータスはApprovedのまま)

​関連情報

​警告の種類

概要

生成される警告

警告文字列の正確な内容

検索画像のチェック

設定可能な項目

例

ブロックリスト一致 (`Declined`を強制)

重複シグナル (ステータスは`Approved`のまま)

関連情報

警告の種類