Correspondance faciale : avertissements et codes d'erreur

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). 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 :

Le code risk — un identifiant stable sur lequel vous pouvez établir des correspondances dans votre code.
Le log_type — information, warning ou error, dérivé des seuils de score de similarité de votre workflow.
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 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 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 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

"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

"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

"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é

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

L’API autonome de correspondance faciale 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 — schéma complet du rapport et statuts.
Avertissements de détection du vivant — avertissements en amont lors de la capture du selfie.
Webhooks — session.status.updated transmet les avertissements dès que l’étape se termine.
Modèles de données — Correspondance faciale — schéma canonique.
Modèles de données — Objet d’avertissement — structure de chaque entrée dans warnings[].

Authentification

Vérification

Surveillance

Plateforme

Correspondance faciale : avertissements et codes d'erreur

Vue d’ensemble

Conditions de refus automatique

Paramètres de vérification configurables

Avertissements émis

Exemples

En cours d’examen — similarité limite

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

Refus automatique — référence manquante

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

Types d’avertissements

Pages connexes

​Vue d’ensemble

​Conditions de refus automatique

​Paramètres de vérification configurables

​Avertissements émis

​Exemples

​En cours d’examen — similarité limite

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

​Refus automatique — référence manquante

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

​Types d’avertissements

​Pages connexes

Vue d’ensemble

Conditions de refus automatique

Paramètres de vérification configurables

Avertissements émis

Exemples

En cours d’examen — similarité limite

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

Refus automatique — référence manquante

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

Types d’avertissements

Pages connexes