Gesichtsabgleich: Warnungen & Fehlercodes

Übersicht

Warnungen im Gesichtsabgleich-Bericht kennzeichnen jeden Zustand, den Didit bei der Durchführung des 1:1-Gesichtsvergleichs festgestellt hat. Sie werden im Array warnings[] für jedes Element von face_matches[] ausgegeben (siehe Gesichtsabgleich-Bericht). Jeder Eintrag enthält zudem feature: "FACEMATCH" sowie die node_id des Workflow-Knotens, der die Warnung ausgelöst hat. Jede Warnung besteht aus drei Ebenen:

Der risk-Code – ein stabiler Bezeichner, den Sie in Ihrem Code abfragen können.
Der log_type – information, warning oder error, abgeleitet aus den Schwellenwerten für den Ähnlichkeitswert Ihres Workflows.
Die Auswirkung auf die Entscheidung – festgelegt durch die Prüf- und Ablehnungsschwellenwerte des Workflows für den Ähnlichkeitswert.

Das Gesichtsabgleich-Modul ist bewusst kompakt gehalten – es gibt genau fünf Risiko-Codes, die unten vollständig aufgeführt sind.

Bedingungen für automatische Ablehnung

Das folgende Risiko setzt den Gesichtsabgleich-Bericht (und die Sitzung) immer auf Declined:

Risiko	Auslöser
`NO_REFERENCE_IMAGE`	Entweder `source_image` (Referenz) oder `target_image` (Selfie) fehlt, sodass kein Vergleich möglich war.

Wenn NO_REFERENCE_IMAGE ausgelöst wird, wird LOW_FACE_MATCH_SIMILARITY unterdrückt (da kein Wert berechnet werden kann). Es gibt eine Ausnahme. Wenn der Ausweisschritt über einen Non-Doc Lookup abgeschlossen wurde, dessen Register kein Porträtfoto zurückgibt und kein Gesicht überprüft, hat der Gesichtsabgleich bauartbedingt kein Vergleichsbild für die Live-Aufnahme. Dies wird als FACE_MATCH_NOT_COMPUTED mit einem null-Wert gemeldet und über face_match_not_computed_action (siehe unten) entschieden, nicht als automatische Ablehnung.

Konfigurierbare Verifizierungseinstellungen

In der Didit-Konsole wird der Ähnlichkeitswert des Gesichtsabgleichs über zwei Schwellenwerte gesteuert (kein Umschalter für Genehmigen/Prüfen/Ablehnen):

Einstellung	Standard	Verhalten
`face_match_score_review_threshold`	70	Wenn `score` ≤ dieser Wert ist, wird `LOW_FACE_MATCH_SIMILARITY` ausgelöst und der Status wechselt zu `In Review`.
`face_match_score_decline_threshold`	50	Wenn `score` ≤ dieser Wert ist, eskaliert dieselbe Warnung zu `error` und der Status wechselt zu `Declined`.

Setzen Sie den Schwellenwert für die Prüfung höher an, wenn Sie zu viele fälschliche Genehmigungen feststellen; setzen Sie den Schwellenwert für die Ablehnung niedriger an, wenn Sie zu viele fälschliche Ablehnungen beobachten. Eine separate Einstellung steuert, was passiert, wenn ein Ähnlichkeitswert überhaupt nicht berechnet werden kann: Es wurde in einem der Bilder kein Gesicht erkannt oder ein Non-Doc Lookup lieferte kein Referenzbild für den Abgleich:

Einstellung	Standard	Verhalten
`face_match_not_computed_action`	`REVIEW`	Aktion, die angewendet wird, sobald das Ergebnis „Konnte nicht berechnet werden“ endgültig ist. `REVIEW` setzt den Bericht auf `In Review`; `DECLINE` setzt ihn auf `Declined`. (Es gibt keine Option zur automatischen Genehmigung – ein Wert, der nie berechnet wurde, wird niemals stillschweigend durchgewinkt.)

Diese Aktion steuert FACE_MATCH_NOT_COMPUTED (kein Gesicht auf dem Dokumentporträt oder überhaupt keine Referenz nach einem Non-Doc Lookup) sowie ein erschöpftes NO_FACE_IN_SELFIE (kein Gesicht im Selfie nach den Wiederholungsversuchen des Benutzers). Wenn das Problem beim Selfie liegt, wird der Benutzer zunächst aufgefordert, die Aufnahme zu wiederholen – siehe unten – und die Aktion greift erst, wenn nach Aufbrauchen des Versuchskontingents immer noch kein Gesicht erkannt werden kann. Auch Fehler aufgrund geringer Ähnlichkeit durchlaufen eine Wiederholungsschleife für die Aufnahme, bevor der Status endgültig feststeht: Der Benutzer erhält insgesamt bis zu face_match_max_attempts Versuche (Standard 3, konfigurierbar auf 2–5 pro Workflow-Knoten) für eine erneute Aufnahme. Ein NO_FACE_IN_SELFIE-Fehler nutzt dieselbe Wiederholungsschleife, da eine erneute, deutlichere Selfie-Aufnahme das Problem beheben kann. Bei einem FACE_MATCH_NOT_COMPUTED-Fehler gibt es keinen Wiederholungsversuch – das Dokumentporträt kann in diesem Schritt nicht erneut aufgenommen werden. Erst wenn das Kontingent erschöpft ist, gilt der Status des letzten Versuchs – und dies wird mit FACE_MATCH_MAX_ATTEMPTS_EXCEEDED protokolliert. In der eigenständigen Face Match API gibt es lediglich einen Ablehnungsschwellenwert (Anfrageoption face_match_score_decline_threshold, Standard 30); jede ausgelöste Warnung führt zur Ablehnung der Anfrage, und NO_REFERENCE_IMAGE wird ausgelöst, wenn überhaupt kein Gesicht verglichen werden konnte.

Erzeugte Warnungen

Risiko	Ursache	Schweregrad	Beeinflusst den Status?	Behebung
`LOW_FACE_MATCH_SIMILARITY`	`score` ≤ `face_match_score_review_threshold`. Wird unterdrückt, wenn auch `NO_REFERENCE_IMAGE` vorliegt.	`warning` zwischen den Schwellenwerten; `error` bei oder unter dem Ablehnungsschwellenwert	`In Review` zwischen den Schwellenwerten; `Declined` bei oder unter dem Ablehnungsschwellenwert	Schwellenwerte anpassen oder über eine manuelle Prüfung akzeptieren.
`FACE_MATCH_NOT_COMPUTED`	Ein Ähnlichkeitswert konnte nicht berechnet werden, da im Dokumentenporträt kein Gesicht erkannt wurde oder der Ausweisschritt eine Abfrage ohne Dokument war, die keine Referenz zum Abgleich hinterlassen hat (ein Register, das kein Porträt zurückibt und kein Gesicht prüft). Wird unterdrückt, wenn auch `NO_REFERENCE_IMAGE` vorliegt.	`warning`, wenn `face_match_not_computed_action` auf `REVIEW` steht; `error`, wenn auf `DECLINE`	`In Review` oder `Declined`, gemäß `face_match_not_computed_action`	Das Dokumentenbild kann in diesem Schritt nicht erneut erfasst werden: Lösen Sie dies per manueller Prüfung oder erfassen Sie das Dokument früher im Ablauf erneut. Setzen Sie nach einer reinen Datenabfrage `face_match_not_computed_action` auf das gewünschte Ergebnis oder verlangen Sie ein Dokument in Ländern, in denen ein biometrischer Abgleich wichtig ist.
`NO_FACE_IN_SELFIE`	Ein Ähnlichkeitswert konnte nicht berechnet werden, da im Selfie des Benutzers kein Gesicht erkannt wurde. Der Benutzer wird aufgefordert, das Selfie erneut aufzunehmen, bevor die Warnung dauerhaft wirksam wird.	`warning`, wenn `face_match_not_computed_action` auf `REVIEW` steht; `error`, wenn auf `DECLINE`	`In Review` oder `Declined`, gemäß `face_match_not_computed_action`, nachdem alle Wiederholungsversuche aufgebraucht sind	Der Benutzer nimmt ein deutlicheres, gut beleuchtetes frontales Selfie erneut auf.
`NO_REFERENCE_IMAGE`	Entweder das Referenzbild oder das Zielbild fehlt (ausgenommen eine Referenz, die bei einer Abfrage ohne Dokument nie erzeugt wurde; dies ist `FACE_MATCH_NOT_COMPUTED`).	`error`	Automatische Ablehnung	Stellen Sie sicher, dass sowohl das Dokumentenporträt als auch das Liveness-Selfie erfasst werden. Übergeben Sie bei der eigenständigen API zwei gültige Gesichtsbilder.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Der Benutzer hat das Kontingent für erneute Erfassungsversuche (`face_match_max_attempts`) nach wiederholten Fehlversuchen wegen geringer Ähnlichkeit aufgebraucht.	`information`	Nein – dokumentiert, dass der berechnete Status des letzten Versuchs (Ablehnung oder Prüfung) angewendet wurde	Erhöhen Sie `face_match_max_attempts` am Workflow-Knoten oder lösen Sie den Fall über eine manuelle Prüfung.

Beispiele

In Prüfung — grenzwertige Ähnlichkeit

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

In Prüfung — Gesichtsabgleich konnte nicht berechnet werden

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

Automatische Ablehnung — fehlende Referenz

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

Wiederholungsversuche aufgebraucht — Status des letzten Versuchs angewendet

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

Die eigenständige Gesichtsabgleich-API gibt dieselbe Warnungsstruktur ohne node_id zurück (der Vergleich ist an keinen Workflow-Knoten gebunden).

Warnungstypen

Jedem Risiko wird basierend auf der Konfiguration Ihrer Anwendung ein Schweregrad zugewiesen. Die drei Schweregrade sind:

Authentifizierung

Verifizierung

Überwachung

Plattform

Gesichtsabgleich: Warnungen & Fehlercodes

Übersicht

Bedingungen für automatische Ablehnung

Konfigurierbare Verifizierungseinstellungen

Erzeugte Warnungen

Beispiele

In Prüfung — grenzwertige Ähnlichkeit

In Prüfung — Gesichtsabgleich konnte nicht berechnet werden

Automatische Ablehnung — fehlende Referenz

Wiederholungsversuche aufgebraucht — Status des letzten Versuchs angewendet

Warnungstypen

Verwandte Themen

​Übersicht

​Bedingungen für automatische Ablehnung

​Konfigurierbare Verifizierungseinstellungen

​Erzeugte Warnungen

​Beispiele

​In Prüfung — grenzwertige Ähnlichkeit

​In Prüfung — Gesichtsabgleich konnte nicht berechnet werden

​Automatische Ablehnung — fehlende Referenz

​Wiederholungsversuche aufgebraucht — Status des letzten Versuchs angewendet

​Warnungstypen

​Verwandte Themen

Übersicht

Bedingungen für automatische Ablehnung

Konfigurierbare Verifizierungseinstellungen

Erzeugte Warnungen

Beispiele

In Prüfung — grenzwertige Ähnlichkeit

In Prüfung — Gesichtsabgleich konnte nicht berechnet werden

Automatische Ablehnung — fehlende Referenz

Wiederholungsversuche aufgebraucht — Status des letzten Versuchs angewendet

Warnungstypen

Verwandte Themen