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

# Correspondance faciale : avertissements et codes d'erreur

> Chaque avertissement Face Match 1:1 de Didit : cause, gravité et remédiation pour faible similarité, image manquante ou tentatives épuisées.

## Vue d'ensemble

Les avertissements du rapport de correspondance faciale signalent chaque condition observée par Didit lors de l'exécution de la comparaison faciale 1:1. Ils apparaissent dans le tableau `warnings[]` de chaque élément de `face_matches[]` (voir [Rapport de correspondance faciale](https://docs.didit.me/fr/core-technology/face-match/report-face-match.md)). Chaque entrée comporte également `feature: "FACEMATCH"` et le `node_id` du nœud de workflow qui l'a émise.

Chaque avertissement comporte trois niveaux :

1. **Le code `risk`** — un identifiant stable sur lequel vous pouvez établir des correspondances dans votre code.
2. **Le `log_type`** — `information`, `warning` ou `error`, dérivé des seuils de score de similarité de votre workflow.
3. **L'impact décisionnel** — défini par les seuils d'examen et de refus du workflow pour le score de similarité.

Le module de correspondance faciale est volontairement restreint — il existe exactement cinq codes de risque, détaillés ci-dessous.

## Conditions de refus automatique

Le risque suivant fait toujours basculer le rapport de correspondance faciale (et la session) à `Declined` :

| Risque | Déclencheur |
| - | - |
| `NO_REFERENCE_IMAGE` | L'un des champs `source_image` (référence) ou `target_image` (selfie) est manquant, aucune comparaison n'a donc été possible. |

Lorsque `NO_REFERENCE_IMAGE` se déclenche, `LOW_FACE_MATCH_SIMILARITY` est supprimé (il n'y a rien à évaluer).

Il existe une exception.
Lorsque l'étape d'identification a été réalisée via une [recherche sans document](https://docs.didit.me/fr/core-technology/id-verification/non-doc-lookup.md) dont le registre ne renvoie aucun portrait et ne vérifie aucun visage, la correspondance faciale n'a par conception rien à comparer à la capture en direct.
Cela est consigné sous le code `FACE_MATCH_NOT_COMPUTED` avec un score `null` et fait l'objet d'une décision selon `face_match_not_computed_action` (ci-dessous), et non d'un refus automatique.

## Paramètres de vérification configurables

Dans la console Didit, le score de similarité de correspondance faciale est régi par deux seuils (sans bascule Approuver/Examiner/Refuser) :

| Paramètre | Valeur par défaut | Comportement |
| - | - | - |
| `face_match_score_review_threshold` | 70 | Lorsque le `score` ≤ cette valeur, `LOW_FACE_MATCH_SIMILARITY` se déclenche et le statut passe à `In Review`. |
| `face_match_score_decline_threshold` | 50 | Lorsque le `score` ≤ cette valeur, le même avertissement passe à `error` et le statut passe à `Declined`. |

Augmentez le seuil d'examen si vous constatez un trop grand nombre de fausses approbations ; diminuez le seuil de refus si vous constatez un trop grand nombre de faux refus.

Un paramètre distinct contrôle ce qui se produit lorsqu'un score de similarité **ne peut pas être calculé du tout** : aucun visage n'a été détecté dans l'une des images, ou une recherche sans document n'a laissé aucune référence à comparer :

| Paramètre | Valeur par défaut | Comportement |
| - | - | - |
| `face_match_not_computed_action` | `REVIEW` | Action appliquée une fois que le résultat « calcul impossible » est définitif. `REVIEW` envoie le rapport en `In Review` ; `DECLINE` le passe à `Declined`. (Il n'existe aucune option d'approbation automatique — un score qui n'a jamais été calculé n'est jamais validé silencieusement.) |

Cette action régit `FACE_MATCH_NOT_COMPUTED` (aucun visage sur le portrait du document, ou aucune référence du tout après une recherche sans document) ainsi qu'un échec `NO_FACE_IN_SELFIE` une fois le nombre de tentatives épuisé (aucun visage dans le selfie après les tentatives de l'utilisateur). Lorsque le selfie pose problème, l'utilisateur est d'abord invité à refaire la capture — voir ci-dessous — et l'action ne s'applique que si aucun visage ne peut être détecté une fois le quota de tentatives épuisé.

Les échecs liés à une faible similarité entrent également dans une boucle de nouvelle tentative de capture avant que le statut ne soit définitivement fixé : l'utilisateur dispose d'un maximum de `face_match_max_attempts` tentatives au total (3 par défaut, configurable de 2 à 5 par nœud de workflow) pour reprendre la capture. Un échec `NO_FACE_IN_SELFIE` utilise la même boucle de nouvelles tentatives, puisqu'une nouvelle capture plus nette du selfie peut résoudre le problème. Un échec `FACE_MATCH_NOT_COMPUTED` n'entraîne **aucune** nouvelle tentative — le portrait du document ne peut pas être recapturé à cette étape. Ce n'est que lorsque le quota de tentatives est épuisé que le statut de la dernière tentative s'applique — et `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` est consigné pour l'enregistrer.

Sur l'[API de correspondance faciale](https://docs.didit.me/fr/standalone-apis/face-match.md) autonome, seul un seuil de refus existe (option de requête `face_match_score_decline_threshold`, 30 par défaut) ; tout avertissement déclenché entraîne le refus de la requête, et `NO_REFERENCE_IMAGE` se déclenche si aucun visage n'a pu être comparé.

## Avertissements émis

| Risque | Cause | Gravité | Affecte le statut ? | Résolution |
| - | - | - | - | - |
| `LOW_FACE_MATCH_SIMILARITY` | `score` ≤ `face_match_score_review_threshold`. Supprimé lorsque `NO_REFERENCE_IMAGE` est également présent. | `warning` entre les seuils ; `error` au seuil de refus ou en dessous | `In Review` entre les seuils ; `Declined` au seuil de refus ou en dessous | Ajustez les seuils ou acceptez via un examen manuel. |
| `FACE_MATCH_NOT_COMPUTED` | Un score de similarité n'a pas pu être calculé car aucun visage n'a été détecté sur la **photo du document**, ou parce que l'étape d'identité était une [consultation sans document](https://docs.didit.me/fr/core-technology/id-verification/non-doc-lookup.md) qui n'a laissé aucune référence à laquelle comparer (un registre qui ne renvoie aucun portrait et ne vérifie aucun visage). Supprimé lorsque `NO_REFERENCE_IMAGE` est également présent. | `warning` lorsque `face_match_not_computed_action` est `REVIEW` ; `error` lorsque `DECLINE` | `In Review` ou `Declined`, selon `face_match_not_computed_action` | L'image du document ne peut pas être recapturée à cette étape : résolvez le dossier via un examen manuel, ou recapturez le document plus tôt dans le flux. Après une recherche basée uniquement sur les données, définissez `face_match_not_computed_action` sur le résultat souhaité, ou exigez un document dans les pays où une correspondance biométrique est importante. |
| `NO_FACE_IN_SELFIE` | Un score de similarité n'a pas pu être calculé car aucun visage n'a été détecté sur le **selfie** de l'utilisateur. L'utilisateur est invité à reprendre le selfie avant que cet avertissement ne soit retenu définitivement. | `warning` lorsque `face_match_not_computed_action` est `REVIEW` ; `error` lorsque `DECLINE` | `In Review` ou `Declined`, selon `face_match_not_computed_action`, une fois les nouvelles tentatives épuisées | L'utilisateur recapture un selfie plus net, bien éclairé et de face. |
| `NO_REFERENCE_IMAGE` | L'image de référence ou l'image cible est manquante (à l'exception d'une référence qu'une consultation sans document n'a jamais produite, ce qui correspond à `FACE_MATCH_NOT_COMPUTED`). | `error` | **Refus automatique** | Assurez-vous que la photo du document et le selfie de détection du vivant sont tous deux capturés. Pour l'API autonome, transmettez deux images de visage valides. |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | L'utilisateur a épuisé le quota de tentatives de capture (`face_match_max_attempts`) après des échecs répétés liés à une faible similarité. | `information` | Non — consigne que le statut calculé de la dernière tentative (refus ou examen) a été appliqué | Augmentez `face_match_max_attempts` sur le nœud du workflow, ou résolvez le dossier via un examen manuel. |

## Exemples

### En cours d'examen — similarité limite

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

### En cours d'examen — la correspondance faciale n'a pas pu être calculée

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

### Refus automatique — référence manquante

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

### Tentatives épuisées — statut de la dernière tentative appliqué

```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]
>
> L'API autonome de [correspondance faciale](https://docs.didit.me/fr/standalone-apis/face-match.md) renvoie la même structure d'avertissement sans `node_id` (la comparaison n'est pas liée à un nœud de workflow).

## Types d'avertissements

Chaque risque se voit attribuer une gravité en fonction de la configuration de votre application. Les trois niveaux de gravité sont :

## Pages connexes

* [Rapport de correspondance faciale](https://docs.didit.me/fr/core-technology/face-match/report-face-match.md) — schéma complet du rapport et statuts.
* [Avertissements de détection du vivant](https://docs.didit.me/fr/core-technology/liveness/warnings-liveness.md) — avertissements en amont lors de la capture du selfie.
* [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) — `session.status.updated` transmet les avertissements dès que l'étape se termine.
* [Modèles de données — Correspondance faciale](https://docs.didit.me/fr/reference/data-models.md#correspondance-faciale) — schéma canonique.
* [Modèles de données — Objet d'avertissement](https://docs.didit.me/fr/reference/data-models.md#objet-d’avertissement) — structure de chaque entrée dans `warnings[]`.


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