Gesichtssuche 1:N: Warnungen und Fehlercodes

Übersicht

Face Search gibt eine kleine Reihe von Warnungen aus, damit Ihr Team nachvollziehen kann, warum eine Suche Approved oder Declined zurückgegeben hat. Warnungen werden im Array face_search.warnings[] der Antwort auf POST /v3/face-search/ zurückgegeben (siehe Bericht zur Gesichtssuche). Warnungen haben hier im Vergleich zu Workflow-Warnungen eine vereinfachte Struktur: Es gibt keine node_id. Der dokumentierte Antwortvertrag deklariert fünf Felder – risk, additional_data, log_type, short_description, long_description – und die Laufzeit-Payload enthält zusätzlich feature, was an diesem Endpoint immer "LIVENESS" ist.

Erzeugte Warnungen

Risiko	Ursache	Schweregrad (`log_type`)	Beeinflusst Status	Empfohlene Behebung
`FACE_IN_BLOCKLIST`	Das Suchbild stimmt mit einem Gesicht in der Gesichts-Sperrliste Ihrer Anwendung oberhalb des Ähnlichkeitsbereichs mit hoher Konfidenz überein.	`error`	Erzwingt `Declined`.	Benutzer ablehnen. Untersuchen Sie die verknüpfte Sitzung über `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	Ein Gesicht auf der Sperrliste stimmte innerhalb des niedrigeren Ähnlichkeitsbereichs für mögliche Treffer unterhalb des Bereichs mit hoher Konfidenz überein.	`error`	Erzwingt `Declined` bei der eigenständigen Face Search API (strenger als die Liveness-Prüfung im Workflow, die dieses Risiko zur Prüfung weiterleitet).	Manuelle Prüfung. Bestätigen Sie den Treffer anhand des ursprünglichen Sperrlisten-Nachweises, bevor Sie handeln.
`MULTIPLE_FACES_DETECTED`	Im übermittelten Suchbild wurde mehr als ein Gesicht gefunden. Die Suche wird dennoch ausgeführt, wobei das größte erkannte Gesicht verwendet wird.	`warning`	Keine – führt für sich allein nie zu einer Ablehnung.	Erneut aufnehmen, sodass nur eine Person im Bildausschnitt zu sehen ist, falls das größte Gesicht nicht die vorgesehene Person ist.
`DUPLICATED_FACE`	Das Gesicht stimmte oberhalb des Bereichs mit hoher Konfidenz mit einem Gesicht aus einer genehmigten Sitzung oder einem importierten Benutzerprofil-Gesicht überein. Der eigenständige Endpoint schließt Sitzungen mit identischen `vendor_data` nicht aus, sodass ein wiederkehrender Benutzer mit seinen eigenen früheren Sitzungen übereinstimmt.	`information`	Keine – Duplikate werden als Signal ausgegeben, nicht als Ablehnungen.	Untersuchen Sie die verknüpfte Sitzung über `additional_data.duplicated_session_id`. Entscheiden Sie, ob Sie Konten auf Ihrer Seite sperren oder zusammenführen möchten.
`POSSIBLE_DUPLICATED_FACE`	Wie `DUPLICATED_FACE`, jedoch liegt die Ähnlichkeit im niedrigeren Bereich für mögliche Treffer statt im Bereich mit hoher Konfidenz.	`information`	Keine.	Manuelle Prüfung, bevor die beiden Datensätze als dieselbe Person behandelt werden.

Erzeuger: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); Statusableitung: get_face_search_status (apis/views/face_search.py:242-248), die nur bei den beiden Sperrlisten-Risiken ablehnt. Wichtige Ausgaberegeln:

Sperrliste hat Vorrang vor Duplikaten. Ein bestätigter Sperrlisten-Treffer unterdrückt DUPLICATED_FACE, und ein möglicher Sperrlisten-Treffer unterdrückt POSSIBLE_DUPLICATED_FACE – Sie erhalten niemals beide Einträge eines Paares für denselben Konfidenzbereich.
additional_data verweist nur auf das erste übereinstimmende Gesicht, selbst wenn matches[] mehrere enthält. Sperrlisten-Warnungen enthalten {blocklisted_session_id, blocklisted_session_number, api_service}; Duplikat-Warnungen enthalten {duplicated_session_id, duplicated_session_number, api_service}; MULTIPLE_FACES_DETECTED enthält null. Der Wert von api_service ist in Großbuchstaben angegeben (z. B. PASSIVE_LIVENESS) oder null bei Workflow-Sitzungen.
Gesichter auf der Positivliste unterdrücken Duplikat-Warnungen – ein Treffer mit hoher Konfidenz auf der Positivliste entfernt DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (Sperrlisten-Warnungen werden dadurch nie entfernt).

Exakte Warnungstexte

Risiko	`short_description`	`long_description`
`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.
`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.
`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.

Suchbild-Prüfung

Wenn in user_image kein Gesicht erkannt wird, weist die API die Anfrage mit HTTP 400 und {"error": "No face detected in the image"} ab, bevor ein face_search-Objekt erstellt wird – daher erscheint eine NO_FACE_DETECTED-Warnung niemals in einer erfolgreichen Antwort der Gesichtssuche. Dies wird als error-String auf oberster Ebene zurückgegeben, nicht in warnings[].

Konfigurierbare Einstellungen

Die Ähnlichkeitsbereiche, die bestätigte Treffer (FACE_IN_BLOCKLIST, DUPLICATED_FACE) von möglichen Treffern (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) trennen, sind intern fest vorgegeben – anwendungsspezifische Schwellenwert-Anpassungen gelten für die Liveness-Prüfung im Workflow, nicht für diesen Endpoint. Folgende Optionen können Sie pro Anfrage steuern:

search_type (most_similar, Standard | blocklisted_or_approved) – most_similar stuft jedes registrierte Gesicht nach Ähnlichkeit ein; blocklisted_or_approved beschränkt die Kandidaten auf Gesichter auf der Sperrliste, Gesichter auf der Positivliste, Gesichter aus genehmigten Sitzungen sowie importierte Benutzerprofil-Gesichter, wobei Einträge auf der Sperrliste an erster Stelle stehen.
save_api_request (Standard true) – speichert den Aufruf dauerhaft als Sitzung vom Typ API und registriert das gesuchte Gesicht in Ihrem Gesichtssuch-Index. Gesichter, die durch Face-Search-Aufrufe registriert wurden, werden von zukünftigen Face-Search-Ergebnissen ausgeschlossen. Setzen Sie diesen Wert auf false, um eine Abfrage durchzuführen, ohne zu speichern oder zu registrieren.
rotate_image (Standard false) – versucht 90-Grad-Drehungen und behält die Ausrichtung mit der besten Gesichtserkennung bei; nützlich, wenn die EXIF-Ausrichtung fehlt.

Beispiele

Treffer auf der Sperrliste (erzwingt `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."
    }
  ]
}

Duplikatsignal (Status bleibt `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."
    }
  ]
}

Authentifizierung

Verifizierung

Überwachung

Plattform

Gesichtssuche 1:N: Warnungen und Fehlercodes

Übersicht

Erzeugte Warnungen

Exakte Warnungstexte

Suchbild-Prüfung

Konfigurierbare Einstellungen

Beispiele

Treffer auf der Sperrliste (erzwingt `Declined`)

Duplikatsignal (Status bleibt `Approved`)

Verwandte Themen

Warnungstypen

​Übersicht

​Erzeugte Warnungen

​Exakte Warnungstexte

​Suchbild-Prüfung

​Konfigurierbare Einstellungen

​Beispiele

​Treffer auf der Sperrliste (erzwingt Declined)

​Duplikatsignal (Status bleibt Approved)

​Verwandte Themen

​Warnungstypen

Übersicht

Erzeugte Warnungen

Exakte Warnungstexte

Suchbild-Prüfung

Konfigurierbare Einstellungen

Beispiele

Treffer auf der Sperrliste (erzwingt `Declined`)

Duplikatsignal (Status bleibt `Approved`)

Verwandte Themen

Warnungstypen