Recherche faciale 1:N : avertissements et codes d'erreur

Vue d’ensemble

La Recherche faciale émet un ensemble restreint d’avertissements afin que votre équipe puisse comprendre pourquoi une recherche a renvoyé Approved ou Declined. Les avertissements sont renvoyés dans le tableau face_search.warnings[] de la réponse POST /v3/face-search/ (voir rapport de Recherche faciale). Les avertissements utilisent ici une structure réduite par rapport aux avertissements de workflow : il n’y a pas de node_id. Le contrat de réponse documenté déclare cinq champs — risk, additional_data, log_type, short_description, long_description — et le payload d’exécution contient en plus feature, qui vaut toujours "LIVENESS" sur cet endpoint.

Avertissements générés

Risque	Cause	Gravité (`log_type`)	Impact sur le statut	Mesure recommandée
`FACE_IN_BLOCKLIST`	L’image recherchée correspond à un visage figurant sur la liste de blocage de visages de votre application, au-dessus de la plage de similarité de haute confiance.	`error`	Force `Declined`.	Rejeter l’utilisateur. Examiner la session liée via `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Un visage de la liste de blocage a été mis en correspondance dans la plage de similarité inférieure « possible », en dessous de la plage de haute confiance.	`error`	Force `Declined` sur l’API Face Search autonome (plus strict que la vérification de détection du vivant du workflow, qui envoie ce risque en révision).	Examen manuel. Confirmer la correspondance par rapport aux éléments d’origine de la liste de blocage avant d’agir.
`MULTIPLE_FACES_DETECTED`	Plus d’un visage a été détecté dans l’image de recherche envoyée. La recherche s’exécute quand même, en utilisant le visage le plus grand détecté.	`warning`	Aucun — ne refuse jamais à lui seul.	Effectuer une nouvelle capture avec un seul sujet dans le cadre si le plus grand visage n’est pas celui souhaité.
`DUPLICATED_FACE`	Le visage correspond, au-dessus de la plage de haute confiance, à un visage issu d’une session approuvée ou à un visage de profil utilisateur importé. L’endpoint autonome n’exclut pas les sessions ayant le même `vendor_data`, de sorte qu’un utilisateur récurrent correspond à ses propres sessions antérieures.	`information`	Aucun — les doublons sont remontés comme un signal, pas comme des refus.	Examiner la session liée via `additional_data.duplicated_session_id`. Décider de bloquer ou de fusionner les comptes de votre côté.
`POSSIBLE_DUPLICATED_FACE`	Identique à `DUPLICATED_FACE`, mais la similarité se situe dans la plage inférieure « possible » plutôt que dans la plage de haute confiance.	`information`	Aucun.	Examen manuel avant de traiter les deux enregistrements comme étant la même personne.

Producteur : FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330) ; dérivation du statut : get_face_search_status (apis/views/face_search.py:242-248), qui refuse uniquement pour les deux risques liés à la liste de blocage. Règles d’émission à connaître :

La liste de blocage a la priorité sur les doublons. Une correspondance confirmée sur liste de blocage supprime DUPLICATED_FACE, et une correspondance possible sur liste de blocage supprime POSSIBLE_DUPLICATED_FACE — vous ne recevez jamais les deux membres d’une paire pour la même plage de confiance.
additional_data fait uniquement référence au premier visage correspondant, même lorsque matches[] en contient plusieurs. Les avertissements de liste de blocage contiennent {blocklisted_session_id, blocklisted_session_number, api_service} ; les avertissements de doublon contiennent {duplicated_session_id, duplicated_session_number, api_service} ; MULTIPLE_FACES_DETECTED contient null. La valeur de api_service est en majuscules (par ex. PASSIVE_LIVENESS) ou null pour les sessions de workflow.
Les visages sur liste d’autorisation suppriment les avertissements de doublon — une correspondance de haute confiance sur la liste d’autorisation efface DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (elle n’efface jamais les avertissements de liste de blocage).

Chaînes exactes des avertissements

Risque	`short_description`	`long_description`
`FACE_IN_BLOCKLIST`	Visage sur la liste de blocage	Le système a identifié un visage sur la liste de blocage, ce qui signifie que le visage n’est pas autorisé à être vérifié.
`POSSIBLE_FACE_IN_BLOCKLIST`	Visage possible sur la liste de blocage	Le système a identifié un visage possible sur la liste de blocage, ce qui signifie que le visage n’est pas autorisé à être vérifié.
`DUPLICATED_FACE`	Visage dupliqué d’une autre session approuvée	Le système a identifié un visage dupliqué provenant d’une autre session approuvée, nécessitant un examen approfondi.
`POSSIBLE_DUPLICATED_FACE`	Visage possiblement dupliqué provenant d’une autre session approuvée	Le système a identifié un possible visage dupliqué provenant d’une autre session approuvée, nécessitant un examen approfondi.
`MULTIPLE_FACES_DETECTED`	Plusieurs visages détectés	Plusieurs visages ont été détectés dans l’image de détection du vivant. Le système utilise le plus grand visage pour la vérification du vivant et la comparaison faciale, mais la présence de plusieurs visages peut nécessiter un examen supplémentaire.

Contrôle de l’image de recherche

Lorsqu’aucun visage n’est détecté dans user_image, l’API rejette la requête avec un code HTTP 400 et {"error": "No face detected in the image"} avant qu’un objet face_search ne soit créé — ainsi, un avertissement NO_FACE_DETECTED n’apparaît jamais dans une réponse de Recherche faciale réussie. Cela est renvoyé sous forme de chaîne error de premier niveau, et non dans warnings[].

Paramètres configurables

Les plages de similarité qui séparent les correspondances confirmées (FACE_IN_BLOCKLIST, DUPLICATED_FACE) des correspondances possibles (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) sont définies de manière interne — l’ajustement des seuils par application s’applique à la vérification de détection du vivant du workflow, pas à cet endpoint. Les options que vous contrôlez par requête sont :

search_type (most_similar, par défaut | blocklisted_or_approved) — most_similar classe chaque visage enrôlé par similarité ; blocklisted_or_approved restreint les candidats aux visages sur liste de blocage, aux visages sur liste d’autorisation, aux visages issus de sessions approuvées et aux visages de profils utilisateurs importés, en classant les entrées sur liste de blocage en premier.
save_api_request (true par défaut) — conserve l’appel sous la forme d’une session de type API et enrôle le visage recherché dans votre index de recherche faciale. Les visages enrôlés par des appels de Recherche faciale sont exclus des futurs résultats de Recherche faciale. Définissez à false pour interroger sans stocker ni enrôler.
rotate_image (false par défaut) — tente des rotations de 90 degrés et conserve l’orientation offrant la meilleure détection de visage ; utile lorsque l’orientation EXIF est absente.

Exemples

Correspondance dans la liste de blocage (force `Declined`)

{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}

Signal de doublon (le statut reste `Approved`)

{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "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."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}

Ressources associées

Rapport de Recherche faciale — structure complète de la réponse
Référence de l’API de Recherche faciale — paramètres de requête
Avertissements de Correspondance faciale — avertissements 1:1 entre le selfie et le document (distincts de la Recherche faciale)
Modèles de données — Recherche faciale — schéma canonique

Authentification

Vérification

Surveillance

Plateforme

Recherche faciale 1:N : avertissements et codes d'erreur

Vue d’ensemble

Avertissements générés

Chaînes exactes des avertissements

Contrôle de l’image de recherche

Paramètres configurables

Exemples

Correspondance dans la liste de blocage (force `Declined`)

Signal de doublon (le statut reste `Approved`)

Ressources associées

Types d’avertissements

​Vue d’ensemble

​Avertissements générés

​Chaînes exactes des avertissements

​Contrôle de l’image de recherche

​Paramètres configurables

​Exemples

​Correspondance dans la liste de blocage (force Declined)

​Signal de doublon (le statut reste Approved)

​Ressources associées

​Types d’avertissements

Vue d’ensemble

Avertissements générés

Chaînes exactes des avertissements

Contrôle de l’image de recherche

Paramètres configurables

Exemples

Correspondance dans la liste de blocage (force `Declined`)

Signal de doublon (le statut reste `Approved`)

Ressources associées

Types d’avertissements