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

# 顔照合（Face Match）の警告とエラーコード

> Didit顔照合（1:1）モジュールが出すすべての警告（類似度の低さ、参照画像の欠落、再試行回数の上限到達）について、原因・重大度・対処法を解説します。

## 概要

顔照合レポートの警告は、Diditが1:1の顔比較を実行する過程で検出したすべての状態を示します。警告は`face_matches[]`の各項目にある`warnings[]`配列に格納されます([顔照合レポート](https://docs.didit.me/ja/core-technology/face-match/report-face-match.md)を参照)。各エントリには`feature: "FACEMATCH"`と、その警告を発生させたワークフローノードの`node_id`も含まれます。

すべての警告は3つの要素で構成されます。

1. **`risk`コード**: コード内で照合に使用できる安定した識別子です。
2. **`log_type`**: `information`、`warning`、`error`のいずれかで、ワークフローの類似度スコアのしきい値から決まります。
3. **判定への影響**: 類似度スコアに対するワークフローのレビューしきい値と却下しきい値によって決まります。

顔照合モジュールは意図的に小さく設計されており、リスクコードは5つだけです。以下にすべて記載します。

## 自動却下の条件

次のリスクが発生すると、顔照合レポート(およびセッション)は必ず`Declined`になります。

| リスク | トリガー |
| - | - |
| `NO_REFERENCE_IMAGE` | `source_image`(参照画像)または`target_image`(セルフィー)のいずれかが欠けているため、比較を実行できませんでした。 |

`NO_REFERENCE_IMAGE`が発生した場合、`LOW_FACE_MATCH_SIMILARITY`は抑制されます(スコアリングの対象が存在しないため)。

ただし、例外が1つあります。
本人確認ステップが[書類を使わない照会](https://docs.didit.me/ja/core-technology/id-verification/non-doc-lookup.md)で完了し、その照会先の登録簿が顔写真を返さず顔の確認も行わない場合、顔照合にはライブ撮影画像と比較する対象が仕様上存在しません。
この場合は自動却下ではなく、スコアが`null`の`FACE_MATCH_NOT_COMPUTED`として報告され、後述の`face_match_not_computed_action`によって判定されます。

## 設定可能な検証設定

Diditコンソールでは、顔照合の類似度スコアは2つのしきい値によって制御されます(承認/レビュー/却下の切り替えはありません)。

| 設定 | デフォルト | 動作 |
| - | - | - |
| `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/ja/standalone-apis/face-match.md)には却下しきい値のみが存在します(リクエストオプション`face_match_score_decline_threshold`、デフォルトは30)。警告が1つでも発生するとリクエストは却下され、顔をまったく比較できなかった場合は`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` | **書類の顔写真**で顔が検出されなかったため、またはIDステップが比較対象の参照画像を残さない[書類なし照会](https://docs.didit.me/ja/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では、有効な顔画像を2枚渡してください。 |
| `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]
>
> スタンドアロンの[顔照合API](https://docs.didit.me/ja/standalone-apis/face-match.md)は、`node_id`を除いた同じ形式の警告を返します（比較がワークフローノードに紐付かないため）。

## 警告の種類

各リスクには、アプリケーションの設定に基づいて重大度が割り当てられます。重大度は次の3種類です。

## 関連情報

* [顔照合レポート](https://docs.didit.me/ja/core-technology/face-match/report-face-match.md)：レポートの完全なスキーマとステータス。
* [ライブネスの警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md)：セルフィー撮影に関する前段の警告。
* [Webhook](https://docs.didit.me/ja/integration/webhooks.md)：ステップが完了するとすぐに、`session.status.updated`には警告が含まれます。
* [データモデル：顔照合](https://docs.didit.me/ja/reference/data-models.md#顔照合)：正式なスキーマ。
* [データモデル：警告オブジェクト](https://docs.didit.me/ja/reference/data-models.md#警告オブジェクト)：`warnings[]`の各エントリーの形式。


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