> ## 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生体認証の警告への対処方法：LOW_LIVENESS_SCORE、顔攻撃、ブロックリスト一致、顔照合の類似度不足。しきい値と却下アクションを設定できます。

生体認証は、ライブネスチェックと、セッション作成時に特定された参照用の顔（指定された`portrait_image`、または`vendor_data`で検索されたユーザーの保存済みの顔）との任意の1:1顔照合を組み合わせたものです。各ステップは、V3の判定ペイロードにそれぞれ独自の警告を出力します。このページでは、すべてのコード、その表示場所、そしてしきい値が最終的なセッションステータスにどう反映されるかを説明します。

## 概要

生体認証セッションが実行されると、Diditは次の処理を行います。

* 3Dアクション、フラッシュ、またはパッシブライブネス（`method`: `ACTIVE_3D`、`FLASHING`、または`PASSIVE`）を使ってライブのセルフィーを撮影します。
* 撮影画像から最も大きい顔を抽出し、そのライブネスをスコアリングします。
* ワークフローに顔照合が含まれている場合、撮影した顔をセッションの参照顔（指定された`portrait_image`またはユーザーの保存済みの顔）と照合します。
* 各ステップの結果と警告をセッションの判定に書き込みます。

警告は、プラットフォーム全体で共通の[警告オブジェクト](https://docs.didit.me/ja/reference/data-models.md#警告オブジェクト)の形式（`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`）に従います。

## 警告が表示される場所

| 判定レスポンスのキー | 警告の機能タグ | 発生するタイミング |
| - | - | - |
| `liveness_checks[].warnings[]` | `LIVENESS` | ライブネスのスコアリング、顔の品質、輝度、複数の顔、ブロックリスト／許可リスト／重複顔のチェック。 |
| `face_matches[].warnings[]` | `FACEMATCH` | セッションの参照顔（指定された`portrait_image`またはユーザーの保存済みの顔）との顔照合。 |

一般的な生体認証セッションでは、各arrayには項目が1つあります。複数のインスタンスを含むワークフローでは、各警告の`node_id`によって、どのステップが警告を出力したかを区別できます。

## 自動却下の条件

次の警告は、ワークフローの設定にかかわらず、常にそのステップを却下します（`log_type: "error"`）。

| リスク | 機能 | 自動却下される理由 |
| - | - | - |
| `FACE_IN_BLOCKLIST` | `LIVENESS` | 顔が顔ブロックリストのエントリと一致しました。 |
| `NO_FACE_DETECTED` | `LIVENESS` | ライブネスの撮影中に顔が検出されなかったか、ユーザーが撮影の再試行回数を使い切りました。 |
| `LIVENESS_FACE_ATTACK` | `LIVENESS` | プレゼンテーション攻撃（マスク、画面のリプレイ、ディープフェイク系のなりすまし）が検出されました。 |
| `NO_REFERENCE_IMAGE` | `FACEMATCH` | 照合に使用できる参照画像がありませんでした。この警告が発生した場合、`LOW_FACE_MATCH_SIMILARITY`は出力されません。 |

`NO_FACE_DETECTED`が発生した場合、`LOW_LIVENESS_SCORE`は出力されません（スコアリングする顔がないため）。

## 設定可能なしきい値とアクション

次の警告はスコアリングされた後、ワークフローごとに設定したしきい値とアクションによってステータスに対応付けられます。

| リスク | 機能 | 設定可能な動作 |
| - | - | - |
| `LOW_LIVENESS_SCORE` | `LIVENESS` | スコアがレビューのしきい値以下 → `In Review`、却下のしきい値以下 → `Declined`。 |
| `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | スコアがレビューのしきい値（デフォルト70）以下 → `In Review`、却下のしきい値（デフォルト50）以下 → `Declined`。 |
| `LOW_FACE_QUALITY` | `LIVENESS` | レビューのしきい値（デフォルト15）→ `In Review`、却下のしきい値（デフォルト0、つまり却下は無効）→ `Declined`。パッシブライブネスのみ。 |
| `LOW_FACE_LUMINANCE` | `LIVENESS` | 最小輝度のしきい値（デフォルト20）を下回った場合: アクションなし／レビュー（デフォルト）／却下。パッシブライブネスのみ。 |
| `HIGH_FACE_LUMINANCE` | `LIVENESS` | 最大輝度のしきい値（デフォルト80）を上回った場合: アクションなし／レビュー（デフォルト）／却下。パッシブライブネスのみ。 |
| `MULTIPLE_FACES_DETECTED` | `LIVENESS` | 複数の顔が撮影された場合: アクションなし（デフォルト）／レビュー／却下。パッシブライブネスのみ。 |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | 共通の重複顔アクションを1つ設定: 他のユーザーの承認済みまたはインポートされた顔との一致に対して、アクションなし（デフォルト）／レビュー／却下。 |
| `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | 専用のアクション（`face_liveness_duplicated_face_name_mismatch_action`）: アクションなし／レビュー（デフォルト）／却下。一致したセッションの本人情報が、このセッションで確定した氏名と一致しない場合に、`DUPLICATED_FACE`とあわせて出力されます。詳しくは[ライブネスの警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md#セッション横断の顔照合)を参照してください。 |

`POSSIBLE_FACE_IN_BLOCKLIST`（`LIVENESS`）は設定**できません**。信頼度の低いブロックリスト一致は、常にレビューに回されます（`log_type: "warning"`）。

## 撮影の再試行

修正可能な撮影品質のリスク（低スコア、顔が検出されない、品質不良、輝度、複数の顔、および顔照合での低い類似度）のみが原因の失敗は、ステータスが確定する前に再試行ループに入ります。ユーザーには合計で最大`face_liveness_max_attempts`／`face_match_max_attempts`回の試行が与えられます（デフォルト3回、ワークフローのノードごとに2～5回で設定可能）。試行回数を使い切ると、最後の試行で算出されたステータスが適用され、その記録として`LIVENESS_MAX_ATTEMPTS_EXCEEDED`または`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`が`information`としてログに残ります。

## ライブネス検知の警告

APIは、以下の`short_description`と`long_description`の文字列をそのまま返します。

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_LIVENESS_SCORE` | Low liveness score(ライブネススコアが低い) | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.(ライブネスチェックのスコアが低く、生体ではない顔画像が使用されたか、生体データの品質が低い可能性があります。) |
| `NO_FACE_DETECTED` | No Face Detected in liveness(ライブネスチェックで顔が検出されない) | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.(ライブネスチェック中に顔を識別できませんでした。画質の低さ、不適切な位置、または技術的な問題が原因である可能性があります。) |
| `LIVENESS_FACE_ATTACK` | Liveness Face Attack(ライブネスチェックに対する顔なりすまし攻撃) | The system detected a potential attempt to bypass the liveness check.(ライブネスチェックを回避しようとする試みの可能性を検出しました。) |
| `FACE_IN_BLOCKLIST` | 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.(ブロックリストに登録されている可能性のある顔を識別しました。この顔は認証が許可されていません。) |
| `FACE_IN_ALLOWLIST` | Face in allowlist(許可リストに登録された顔) | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal.(顔がアプリケーションの顔許可リストと一致したため、このシグナルについては重複顔に対するアクションがスキップされました。) |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Possible face in allowlist(許可リストに登録された顔の可能性) | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal.(顔がアプリケーションの顔許可リストと一致した可能性があるため、このシグナルについては重複顔の可能性に対するアクションがスキップされました。) |
| `DUPLICATED_FACE` | Duplicated face from other approved session(他の承認済みセッションとの重複顔) | 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.(他の承認済みセッションと重複している可能性のある顔を識別しました。追加の調査が必要です。) |
| `DUPLICATED_FACE_NAME_MISMATCH` | Duplicated face under a different name(異なる氏名での重複顔) | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.(同じ顔が別のセッションですでに承認されていますが、氏名が異なります。重複した顔の本人情報がこのセッションで申告された本人情報と一致しないため、なりすまし詐欺の強い兆候です。) |
| `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.(ライブネス画像で複数の顔が検出されました。ライブネス検証と顔照合には最も大きい顔が使用されますが、複数の顔が存在するため追加のレビューが必要になる場合があります。) |
| `LOW_FACE_QUALITY` *(パッシブのみ)* | Low face quality(顔画像の品質が低い) | The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.(顔画像の品質が許容しきい値を下回っており、ライブネス検知の信頼性に影響する可能性があります。カメラの解像度、ピント、または圧縮ノイズが原因である可能性があります。) |
| `LOW_FACE_LUMINANCE` *(パッシブのみ)* | Low face luminance(顔の輝度が低い) | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.(顔画像が暗すぎるため、ライブネス検知の精度に影響する可能性があります。照明条件の改善を推奨します。) |
| `HIGH_FACE_LUMINANCE` *(パッシブのみ)* | High face luminance(顔の輝度が高い) | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.(顔画像が明るすぎるか露出オーバーのため、ライブネス検知の精度に影響する可能性があります。照明を弱めるか、直射光を避けることを推奨します。) |
| `LIVENESS_MAX_ATTEMPTS_EXCEEDED` | Maximum liveness attempts exceeded(ライブネスの最大試行回数を超過) | The maximum number of liveness capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.(ライブネス撮影の最大試行回数に達しました。最後の試行で算出されたステータス(却下またはレビュー)が適用されています。) |

ブロックリスト、許可リスト、重複の一致には、一致したセッションを示す`additional_data`(`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`、対応する`*_session_number`、および`api_service`)が含まれます。これら6つのコードのうち、1件のレポートに含まれるのは1つだけです。例外は`DUPLICATED_FACE_NAME_MISMATCH`で、一致したセッションの本人情報がこのセッションで確定した氏名と一致しない場合に、`DUPLICATED_FACE`に**加えて**出力され、その代わりに出力されることはありません。その`additional_data`には、重複セッションの同じフィールドに加えて`name_match_score`が含まれます。双方で氏名が異なる文字体系で書かれていても、両セッションの身分証明書の発行国が同じで、書類番号または個人番号が完全に一致し、生年月日に矛盾がない場合は、不一致として扱われません。詳しくは[ライブネス検知の警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md#セッション横断の顔照合)をご覧ください。

## 顔照合の警告

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | Low face match similarity(顔照合の類似度が低い) | The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.(提供された画像の顔の特徴が参照画像と十分に一致せず、本人ではない可能性があります。) |
| `NO_REFERENCE_IMAGE` | No source image found for performing face match(顔照合を行うための元画像がない) | A reference image for facial comparison is missing, preventing the system from completing the face matching process.(顔の比較に使う参照画像がないため、顔照合の処理を完了できません。) |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Maximum face match attempts exceeded(顔照合の最大試行回数を超過) | The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.(顔照合用の撮影の最大試行回数に達しました。最後の試行で算出されたステータス(却下またはレビュー)が適用されています。) |

## 顔攻撃による却下の例

```json theme={null}
{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}
```

## 類似度が低くレビュー中となる例

```json theme={null}
{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "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"
        }
      ]
    }
  ]
}
```

スコア(58.70)は却下のしきい値(デフォルト50)とレビューのしきい値(デフォルト70)の間にあるため、警告は`log_type: "warning"`となり、顔照合のステータスは`In Review`になります。この例では、`session_id`が`11111111-2222-3333-4444-555555555555`のセッションで警告が発生しています。参照画像がセッション作成時に保存されたポートレートから取得されたため、`source_image_session_id`にはそのセッション自身のIDが入ります。

## 警告タイプ

各リスクには、アプリケーションの設定に基づいて警告タイプが割り当てられます。警告は3つの重大度のカテゴリに分類されます。

## 関連情報

> [card] [生体認証レポート](https://docs.didit.me/ja/core-technology/biometric-auth/report-biometric-authentication.md)
>
> V3の判定において`liveness_checks[]`と`face_matches[]`が表示される場所。

> [card] [ライブネス検知の警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md)
>
> 重複顔の照合を含む、ライブネス検知の警告の完全なリファレンス。

> [card] [顔照合の警告](https://docs.didit.me/ja/core-technology/face-match/warnings-face-match.md)
>
> 1:1照合における顔照合の警告の完全なリファレンス。


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