> ## 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. # Gesichtssuche 1:N: Warnungen und Fehlercodes > 1:N-Gesichtssuche-Warncodes bei Didit erklärt: Sperrlisten-Treffer, doppelte oder mehrere Gesichter sowie Ablehnung bei fehlendem Gesicht. ## Ü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](https://docs.didit.me/de/core-technology/face-search/report-face-search.md)). 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`) ```json theme={null} { "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`) ```json theme={null} { "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." } ] } ``` ## Verwandte Themen * [Gesichtssuche-Bericht](https://docs.didit.me/de/core-technology/face-search/report-face-search.md) — vollständige Antwortstruktur * [Gesichtssuche-API-Referenz](https://docs.didit.me/de/standalone-apis/face-search.md) — Anfrageparameter * [Gesichtsabgleich-Warnungen](https://docs.didit.me/de/core-technology/id-verification/warnings-id-verification.md) — Warnungen für den 1:1-Abgleich von Selfie und Dokument (getrennt von der Gesichtssuche) * [Datenmodelle — Gesichtssuche](https://docs.didit.me/de/reference/data-models.md#gesichtssuche) — kanonisches Schema ### Warnungstypen This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.