> ## 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.

# Gesichtsabgleich: Warnungen & Fehlercodes

> Alle Warnungen des 1:1-Gesichtsabgleichs von Didit: Ursache, Schweregrad und Behebung bei geringer Ähnlichkeit, fehlendem Referenzbild und mehr.

## Ü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](https://docs.didit.me/de/core-technology/face-match/report-face-match.md)). 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:

1. **Der `risk`-Code** – ein stabiler Bezeichner, den Sie in Ihrem Code abfragen können.
2. **Der `log_type`** – `information`, `warning` oder `error`, abgeleitet aus den Schwellenwerten für den Ähnlichkeitswert Ihres Workflows.
3. **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](https://docs.didit.me/de/core-technology/id-verification/non-doc-lookup.md) 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](https://docs.didit.me/de/standalone-apis/face-match.md) 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](https://docs.didit.me/de/core-technology/id-verification/non-doc-lookup.md) 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

```json theme={null}
"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

```json theme={null}
"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

```json theme={null}
"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

```json theme={null}
"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"
  }
]
```

> [!NOTE]
>
> Die eigenständige [Gesichtsabgleich-API](https://docs.didit.me/de/standalone-apis/face-match.md) 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:

## Verwandte Themen

* [Gesichtsabgleichsbericht](https://docs.didit.me/de/core-technology/face-match/report-face-match.md) — vollständiges Berichtsschema und Status.
* [Liveness-Warnungen](https://docs.didit.me/de/core-technology/liveness/warnings-liveness.md) — vorgelagerte Warnungen bei der Selfie-Erfassung.
* [Webhooks](https://docs.didit.me/de/integration/webhooks.md) — `session.status.updated` überträgt die Warnungen, sobald der Schritt abgeschlossen ist.
* [Datenmodelle — Gesichtsabgleich](https://docs.didit.me/de/reference/data-models.md#gesichtsabgleich) — kanonisches Schema.
* [Datenmodelle — Warnungsobjekt](https://docs.didit.me/de/reference/data-models.md#warnungsobjekt) — die Struktur jedes Eintrags in `warnings[]`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.