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

# Authentification biométrique : avertissements et codes

> Gérez les avertissements biométriques avec Didit : LOW_LIVENESS_SCORE, attaques faciales, listes de blocage et seuils de refus.

L'authentification biométrique combine un contrôle de détection du vivant avec une correspondance faciale 1:1 facultative par rapport au visage de référence déterminé lors de la création de la session (le `portrait_image` fourni ou le visage enregistré de l'utilisateur retrouvé via `vendor_data`). Chaque étape émet ses propres avertissements dans le payload de décision V3. Cette page détaille chaque code, où il apparaît et la façon dont les seuils se traduisent par un statut de session final.

## Vue d'ensemble

Lorsqu'une session d'authentification biométrique s'exécute, Didit :

* Capture un selfie en direct à l'aide de l'action 3D, du flash ou de la détection passive du vivant (`method` : `ACTIVE_3D`, `FLASHING` ou `PASSIVE`).
* Extrait le visage le plus grand de la capture et évalue la détection du vivant.
* Si le workflow inclut la Correspondance faciale, compare le visage capturé au visage de référence de la session (`portrait_image` fourni ou visage enregistré de l'utilisateur).
* Inscrit le résultat de chaque étape ainsi que tout avertissement dans la décision de la session.

Les avertissements conservent la structure partagée de l'[objet d'avertissement](https://docs.didit.me/fr/reference/data-models.md#objet-d’avertissement) utilisée sur l'ensemble de la plateforme : `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description` et `node_id`.

## Où apparaissent les avertissements

| Clé de réponse de décision | Balise de fonctionnalité sur l'avertissement | Quand il se déclenche |
| - | - | - |
| `liveness_checks[].warnings[]` | `LIVENESS` | Évaluation de la vivacité, qualité du visage, luminance, visages multiples et vérifications de liste de blocage / liste d'autorisation / visages dupliqués. |
| `face_matches[].warnings[]` | `FACEMATCH` | Correspondance faciale par rapport au visage de référence de la session (`portrait_image` fourni ou visage enregistré de l'utilisateur). |

Dans une session d'authentification biométrique standard, il y a un élément dans chaque tableau. Dans les workflows multi-instances, le champ `node_id` présent sur chaque avertissement permet de distinguer l'étape qui l'a généré.

## Conditions de refus automatique

Les avertissements suivants entraînent toujours le refus de leur étape (`log_type: "error"`), quelle que soit la configuration de votre workflow :

| Risque | Fonctionnalité | Pourquoi il refuse automatiquement |
| - | - | - |
| `FACE_IN_BLOCKLIST` | `LIVENESS` | Le visage correspond à une entrée de votre liste de blocage des visages. |
| `NO_FACE_DETECTED` | `LIVENESS` | Aucun visage n'a été détecté lors de la capture de vivacité, ou l'utilisateur a épuisé ses tentatives de capture. |
| `LIVENESS_FACE_ATTACK` | `LIVENESS` | Une attaque par présentation a été détectée (masque, relecture sur écran, usurpation de type deepfake). |
| `NO_REFERENCE_IMAGE` | `FACEMATCH` | Aucune image de référence n'était disponible pour effectuer la comparaison. Lorsqu'il se déclenche, `LOW_FACE_MATCH_SIMILARITY` est supprimé. |

Lorsque `NO_FACE_DETECTED` se déclenche, `LOW_LIVENESS_SCORE` est supprimé (il n'y a aucun visage à évaluer).

## Seuils et actions configurables

Ces avertissements font l'objet d'une notation puis sont associés à un statut selon les seuils et actions que vous définissez par workflow :

| Risque | Fonctionnalité | Comportement configurable |
| - | - | - |
| `LOW_LIVENESS_SCORE` | `LIVENESS` | Score inférieur ou égal au seuil d'examen → `In Review` ; inférieur ou égal au seuil de refus → `Declined`. |
| `LOW_FACE_MATCH_SIMILARITY` | `FACEMATCH` | Score inférieur ou égal au seuil d'examen (70 par défaut) → `In Review` ; inférieur ou égal au seuil de refus (50 par défaut) → `Declined`. |
| `LOW_FACE_QUALITY` | `LIVENESS` | Seuil d'examen (15 par défaut) → `In Review` ; seuil de refus (0 par défaut, c.-à-d. refus désactivé) → `Declined`. Détection passive du vivant uniquement. |
| `LOW_FACE_LUMINANCE` | `LIVENESS` | Inférieur au seuil de luminance minimale (20 par défaut) : Aucune action / Examen (par défaut) / Refus. Détection passive du vivant uniquement. |
| `HIGH_FACE_LUMINANCE` | `LIVENESS` | Supérieur au seuil de luminance maximale (80 par défaut) : Aucune action / Examen (par défaut) / Refus. Détection passive du vivant uniquement. |
| `MULTIPLE_FACES_DETECTED` | `LIVENESS` | Aucune action (par défaut) / Examen / Refus lorsque plusieurs visages sont capturés. Détection passive du vivant uniquement. |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS` | Une action partagée pour les visages dupliqués : Aucune action (par défaut) / Examen / Refus pour les correspondances avec les visages approuvés ou importés d'autres utilisateurs. |
| `DUPLICATED_FACE_NAME_MISMATCH` | `LIVENESS` | Action dédiée (`face_liveness_duplicated_face_name_mismatch_action`) : Aucune action / Examen (par défaut) / Refus. Émis aux côtés de `DUPLICATED_FACE` lorsque l'identité de la session correspondante ne concorde pas avec le nom déterminé de cette session — voir [Avertissements de vivacité](https://docs.didit.me/fr/core-technology/liveness/warnings-liveness.md#correspondance-faciale-inter-sessions). |

`POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) n'est **pas** configurable — une correspondance avec une liste de blocage à score de confiance plus faible est toujours transmise pour examen (`log_type: "warning"`).

## Nouvelles tentatives de capture

Les échecs causés uniquement par des risques corrigibles liés à la qualité de capture (score faible, absence de visage, qualité, luminance, visages multiples — et faible similarité lors de la correspondance faciale) entrent dans une boucle de nouvelle tentative avant que le statut ne devienne définitif : l'utilisateur dispose d'un maximum de `face_liveness_max_attempts` / `face_match_max_attempts` tentatives au total (3 par défaut, configurable de 2 à 5 par nœud de workflow). Lorsque le nombre de tentatives alloué est épuisé, le statut calculé de la dernière tentative s'applique et `LIVENESS_MAX_ATTEMPTS_EXCEEDED` ou `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` est consigné avec le type `information` pour en garder une trace.

## Avertissements de détection du vivant

L'API renvoie exactement ces chaînes `short_description` et `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` *(Passif uniquement)* | 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` *(Passif uniquement)* | 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` *(Passif uniquement)* | 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` *(Passif uniquement)* | 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. |

Les correspondances avec une liste de blocage, une liste d'autorisation et les doublons comportent `additional_data` avec la session correspondante (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, le `*_session_number` correspondant et `api_service`). Un seul de ces six codes apparaît par rapport. `DUPLICATED_FACE_NAME_MISMATCH` fait exception : il est émis **en plus de** `DUPLICATED_FACE`, jamais à sa place, lorsque l'identité de la session correspondante ne concorde pas avec le nom résolu de cette session. Son `additional_data` ajoute `name_match_score` aux mêmes champs de session dupliquée. Un nom écrit dans un système d'écriture différent de chaque côté n'est pas considéré comme une non-concordance lorsque les documents d'identité des deux sessions partagent un État de délivrance, un numéro de document ou personnel exact et une date de naissance non contradictoire. Voir [Avertissements de détection du vivant](https://docs.didit.me/fr/core-technology/liveness/warnings-liveness.md#correspondance-faciale-inter-sessions).

## Avertissements de correspondance faciale

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

## Exemple : refusé en raison d'une attaque faciale

```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
}
```

## Exemple : en cours d'examen en raison d'une faible similarité

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

Le score (58.70) se situe entre le seuil de refus (50 par défaut) et le seuil d'examen (70 par défaut), de sorte que l'avertissement porte `log_type: "warning"` et que le statut de correspondance faciale est `In Review`. Dans cet exemple, l'avertissement s'est déclenché sur une session dont le `session_id` est `11111111-2222-3333-4444-555555555555` — `source_image_session_id` porte l'identifiant propre à la session car la référence provenait du portrait enregistré lors de la création de la session.

## Types d'avertissements

Chaque risque se voit attribuer un type d'avertissement en fonction de la configuration de votre application. Les avertissements se répartissent en trois catégories de gravité :

## Voir aussi

> [card] [Rapport d'authentification biométrique](https://docs.didit.me/fr/core-technology/biometric-auth/report-biometric-authentication.md)
>
> Où `liveness_checks[]` et `face_matches[]` apparaissent dans la décision V3.

> [card] [Avertissements de détection du vivant](https://docs.didit.me/fr/core-technology/liveness/warnings-liveness.md)
>
> Référence complète des avertissements de détection du vivant, y compris la correspondance de visages en doublon.

> [card] [Avertissements de correspondance faciale](https://docs.didit.me/fr/core-technology/face-match/warnings-face-match.md)
>
> Référence complète des avertissements de correspondance faciale pour les comparaisons 1:1.


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