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

# Liveness-Erkennung: Warnungen & Fehlercodes

> Alle Liveness-Warnungen von Didit: Gesichtsangriffe, Qualitätsprobleme, Sperrlisten-Treffer und Duplikate samt Ursachen und Behebung.

## Übersicht

Warnungen im Liveness-Bericht kennzeichnen jede Bedingung, die Didit während der Durchführung der Liveness-Prüfung festgestellt hat. Sie werden im `warnings[]`-Array jedes Eintrags in `liveness_checks[]` ausgegeben (siehe [Liveness-Bericht](https://docs.didit.me/de/core-technology/liveness/report-liveness.md)), wobei `feature` auf `"LIVENESS"` gesetzt ist. Jeder Eintrag folgt dem gemeinsamen Aufbau des [Warnungsobjekts](https://docs.didit.me/de/reference/data-models.md#warnungsobjekt): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Jede Warnung hat drei Ebenen:

1. **Der `risk`-Code** — eine feste Kennung, die Sie in Ihrem Code abgleichen können (die unten aufgeführten Codes).
2. **Der `log_type`** — einer der Werte `information`, `warning` oder `error`. Risiken mit automatischer Ablehnung weisen immer `error` auf. Bei konfigurierbaren Risiken wird er von der konfigurierten Aktion abgeleitet: **Keine Aktion** → `information`, **Überprüfung** → `warning`, **Ablehnen** → `error`. Bei schwellenwertbasierten Risiken (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`) lautet er `error`, wenn der Wert den Ablehnungsschwellenwert erreicht oder unterschreitet, und `warning`, wenn er nur den Überprüfungsschwellenwert erreicht oder unterschreitet.
3. **Die Auswirkung auf die Entscheidung** — dasselbe Routing bestimmt den `status` des Liveness-Berichts: Eine Überprüfungsaktion versetzt ihn in `In Review`, eine Ablehnungsaktion (oder jedes Risiko mit automatischer Ablehnung) in `Declined`, und Keine Aktion belässt ihn unverändert.

Einige Risiken werden nur ausgegeben, wenn die Liveness-Methode `PASSIVE` ist (Prüfungen auf mehrere Gesichter, Bildqualität und Gesichtshelligkeit). Die folgenden Tabellen führen alle Liveness-Risikocodes und deren Schweregrade auf — weitere Liveness-Risikocodes existieren nicht.

## Bedingungen für automatische Ablehnung

Die folgenden Risiken versetzen den Liveness-Bericht (und die Sitzung) immer mit `log_type: "error"` in den Status `Declined`:

| Risiko | Auslöser |
| - | - |
| `NO_FACE_DETECTED` | Bei der Liveness-Erfassung wurde kein Gesicht erkannt oder der Benutzer hat alle Wiederholungsversuche aufgebraucht. |
| `LIVENESS_FACE_ATTACK` | Das Modell hat einen Präsentationsangriff erkannt (Maske, Bildschirmwiedergabe, Deepfake-basiertes Spoofing). |
| `FACE_IN_BLOCKLIST` | Das Gesicht stimmt mit einem Eintrag auf der Gesichtssperrliste Ihrer Anwendung überein. |
| `AGE_BELOW_MINIMUM` | Das geschätzte Alter liegt unter dem konfigurierten Mindestalter. Wird nur bei Workflows mit adaptiver Altersverifikation und `AGE_ESTIMATION`-Knoten ausgegeben. |
| `AGE_NOT_DETECTED` | Das Alter konnte nicht geschätzt werden. Wird nur bei Abläufen zur Altersschätzung mit deaktiviertem Fallback auf die Ausweisverifizierung ausgegeben. |

Wenn `NO_FACE_DETECTED` ausgelöst wird, wird `LOW_LIVENESS_SCORE` unterdrückt (es ist kein Gesicht vorhanden, für das ein Score berechnet werden könnte).

## Konfigurierbare Verifizierungseinstellungen

In der Didit-Konsole sind Liveness-Risiken unter den folgenden Workflow-Einstellungen gruppiert:

| Gruppe | Risiken | Konfiguration |
| - | - | - |
| **Liveness-Score-Schwellenwerte** | `LOW_LIVENESS_SCORE` | Überprüfungsschwellenwert + Ablehnungsschwellenwert für `score`. Am oder unter dem Überprüfungsschwellenwert → `In Review`; am oder unter dem Ablehnungsschwellenwert → `Declined`. |
| **Aktion bei doppeltem Gesicht** | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | Eine gemeinsame Einstellung: Keine Aktion (Standard) / Überprüfung / Ablehnen. Wird vollständig übersprungen, wenn sich das übereinstimmende Gesicht auf Ihrer Gesichtszulassungsliste befindet. |
| **Identitätsabweichung bei doppeltem Gesicht** | `DUPLICATED_FACE_NAME_MISMATCH` | Eigene Einstellung (`face_liveness_duplicated_face_name_mismatch_action`): Keine Aktion / Überprüfung (Standard) / Ablehnen. Wird nur ausgewertet, wenn auch `DUPLICATED_FACE` ausgelöst wird — siehe unten. |
| **Gesichtsabgleich bei Liveness-Angriff** | `FACE_MATCHES_LIVENESS_ATTACK` | Eigene Einstellung (`face_liveness_attack_face_match_action`): Keine Aktion (Standard) / Überprüfung. Eine hier konfigurierte Ablehnung wird akzeptiert, jedoch als Überprüfung angewendet. Auch auf dem Knoten für Altersschätzung verfügbar. |
| **Mögliches Gesicht auf Sperrliste** | `POSSIBLE_FACE_IN_BLOCKLIST` | In Workflows nicht konfigurierbar — wird immer zur Überprüfung weitergeleitet (`log_type: "warning"`). |
| **Aktion bei mehreren Gesichtern** *(nur passiv)* | `MULTIPLE_FACES_DETECTED` | Keine Aktion (Standard) / Überprüfung / Ablehnen. |
| **Schwellenwerte für Gesichtsqualität** *(nur passiv)* | `LOW_FACE_QUALITY` | Überprüfungsschwellenwert (Standard 15) + Ablehnungsschwellenwert (Standard 0, d. h. Ablehnung deaktiviert). |
| **Gesichtshelligkeit** *(nur passiv)* | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE` | Min.- / Max.-Schwellenwerte (Standards 20 / 80 auf der normalisierten Skala von 0–100) + eine Aktion pro Richtung (Standard Überprüfung). |
| **Altersschwellenwerte** *(adaptive Workflows / `AGE_ESTIMATION`-Knoten)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED` | Schwellenwerte für Mindest- und Grenzalter; beide Risiken lehnen den Liveness-Schritt automatisch ab. Bei aktiviertem Fallback auf die Ausweisverifizierung leitet der Workflow den Benutzer zu einer Dokumentenprüfung weiter, anstatt die Sitzung zu beenden. |

## Erzeugte Warnungen

### Kern-Liveness

| Risiko | Ursache | Schweregrad | Wirkt sich auf Status aus? | Behebung |
| - | - | - | - | - |
| `NO_FACE_DETECTED` | Während der Aufnahme wurde kein Gesicht erkannt, oder der Benutzer hat die Wiederholungsversuche erschöpft (`MAX_ATTEMPTS_REACHED`). | `error` | **Automatisch abgelehnt** | Aufnahme bei besseren Lichtverhältnissen wiederholen; sicherstellen, dass das Gesicht zentriert ist. |
| `LIVENESS_FACE_ATTACK` | Das Modell hat einen Präsentationsangriff erkannt. | `error` | **Automatisch abgelehnt** | Als Betrug behandeln. Die Sitzung wird automatisch abgelehnt. |
| `LOW_LIVENESS_SCORE` | `score` liegt auf oder unter dem Schwellenwert für manuelle Prüfung des Workflows. Wird unterdrückt, wenn `NO_FACE_DETECTED` ebenfalls vorhanden ist. | `warning`; wird zu `error` eskaliert, wenn der Score auf oder unter dem Ablehnungsschwellenwert liegt | Konfigurierbar (Prüfungs- / Ablehnungsschwellenwerte) | Aufnahme wiederholen; Schwellenwerte anpassen, wenn Sie falsch positive Ergebnisse beobachten. |

### Integrität des Erfassungskanals

Signale für Injection-Angriffe, die vom Client zum Erfassungszeitpunkt gemeldet werden. Im Gegensatz zu Präsentationsangriffen (ein Artefakt, das vor eine echte Kamera gehalten wird) beschreiben diese, dass der Kamera-Feed selbst ersetzt oder abgefangen wurde.

Jedes Signal ist pro Workflow konfigurierbar und standardmäßig auf **keine Aktion** gesetzt, sodass die Aktivierung der Funktion keine Entscheidungen ändert, bis Sie dies explizit festlegen.

| Risiko | Ursache | Konfigurationsschlüssel | Standard |
| - | - | - | - |
| `VIRTUAL_CAMERA_DETECTED` | Das Erfassungsgerät wurde als softwarebasierte virtuelle Kamera (OBS, ManyCam, Snap Camera, DroidCam und ähnliche) statt als physische Kamera identifiziert. | `virtual_camera_action` | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | Das Erfassungsgerät war eine externe Kamera oder eine Capture-Karte statt einer integrierten Kamera. | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED` | Die erfassten Frames weisen Indikatoren für Software-Compositing oder eine Einschleusung in die Kamera-Pipeline anstelle einer echten Live-Aufnahme auf, **oder** die Erfassung wurde auf emulierter oder virtualisierter Hardware (einem Android-Emulator oder einer Desktop-VM) durchgeführt, auf der kein physischer Kamerasensor existiert und jeder Frame vom Host bereitgestellt wird. | `frame_injection_action` | `NO_ACTION` |
| `INJECTION_ATTACK_DETECTED` | Die Erfassung wurde eingeschleust statt von der geräteeigenen Kamera aufgenommen: eine softwarebasierte virtuelle Kamera, ein von der Seite oder durch Browser-Automatisierung erzeugter Kamera-Feed, eine per Hook manipulierte Kamera oder ein an die App angehängtes Instrumentierungs-Tool. `additional_data.reasons` listet nur die Gründe auf, die dies belegen. Signale, die eine echte Person erzeugen kann, lösen dies niemals aus. Bei Liveness und Gesichtsabgleich folgt dies `frame_injection_action`, sodass Selfie-Entscheidungen unverändert bleiben. | `frame_injection_action` | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE` | Bildschirmaufnahme oder Bildschirmfreigabe war während der biometrischen Erfassung auf dem Gerät aktiv. | `screen_capture_action` | `NO_ACTION` |

> [!NOTE]
>
> Browser stellen keinem Anbieter eine Attestierung der Kameraquelle auf Betriebssystemebene zur Verfügung, sodass diese Signale im Web eher erhärtende Hinweise als ein Beweis sind. Im Web bedeutet das Ergebnis `null` **nicht ermittelt** (Gerätebezeichnungen sind nicht verfügbar, bis die Kameraberechtigung erteilt wurde) und löst niemals ein Risiko aus.

Eine virtuelle Kamera wird anhand ihres Gerätenamens identifiziert; eine Kamera, die das Betriebssystem unter einem gewöhnlichen Namen anzeigt, wird daher auf diese Weise nicht erkannt. In einem Android-Emulator wird die neu zugeordnete Kamera wie jede integrierte Kamera bezeichnet, weshalb der Fall der emulierten Hardware stattdessen über `FRAME_INJECTION_SUSPECTED` gemeldet wird: Er wird anhand der Geräteumgebung erkannt – dem Rendering-Stack und dem im User-Agent gemeldeten Gerätemodell – und nicht anhand des Kameranamens. Befunde, die aus der Geräteumgebung stammen, enthalten `additional_data.reason: "emulated_capture_device"`, was sie von der eigenen Frame-Analyse des Liveness-Modells unterscheidet.

> [!NOTE]
>
> Die Erkennung des Geräts über einen Browser ist ein Indiz, keine Attestierung, und ein entschlossener Angreifer kann dies manipulieren. Die nativen mobilen SDKs melden stärkere Integritätssignale auf Betriebssystemebene, die ein Browser nicht sehen kann (Emulator, gerootetes oder gejailbreaktes Gerät, Laufzeit-Hooking, angehängter Debugger), jeweils mit einer eigenen konfigurierbaren Aktion unter [Geräte- und Laufzeitintegrität](https://docs.didit.me/de/core-technology/ip-analysis/warnings-ip-analysis.md#geräte--und-laufzeitintegrität). Diese Signale erhöhen den Aufwand für den Angreifer erheblich, beweisen für sich allein jedoch nicht, dass eine Aufnahme von einem echten Gerät stammt. Geräteintegritätssignale sind unabhängig von der Liveness-Methode, sodass sie mit Passive, 3D Flash oder 3D Action & Flash kombiniert werden können.

### Forensische Plausibilitätsprüfung der Aufzeichnung

`LIVENESS_VIDEO_ANOMALY` wird **serverseitig auf der gespeicherten Liveness-Aufzeichnung** berechnet, unabhängig vom Liveness-Modell. Es erkennt eine sich bewegende Sequenz, die sich über mehrere Zyklen hinweg wiederholt, was auf einen Video-Loop hinweist.

| Risiko | Ursache | Konfigurationsschlüssel | Standard |
| - | - | - | - |
| `LIVENESS_VIDEO_ANOMALY` | Die Aufzeichnung enthält eine sich wiederholende Bewegungssequenz. Kamerastockungen, wiederholte Standbilder, dunkle Anfangssequenzen und langsame Frame-Übertragungen allein lösen dieses Signal nicht aus. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

Legen Sie die Aktion auf Ihrem Liveness- oder Altersschätzungsknoten fest: `NO_ACTION` zeichnet einen Informationsbefund auf, `REVIEW` kann eine bereits entschiedene Verifizierung zu In Prüfung eskalieren, und `DECLINE` kann sie zu Abgelehnt eskalieren. Die Prüfung läuft asynchron ab, sodass eine Eskalation nach dem ersten Ergebnis eintreffen kann. Eine schwerwiegendere bestehende Entscheidung wird nicht herabgestuft, und manuelle Prüfungsentscheidungen bleiben erhalten.

Befunde der Version 2 enthalten `forensics_version: 2`, `repeated_sequence`-Nachweise und `repeated_moving_sequence` in `anomaly_reasons`. Zustellungsmessungen wie `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio` und `max_frame_gap_seconds` bleiben diagnostische Werte; sie können für sich allein kein Replay belegen. Ältere Befunde beschreiben die damals verwendete Version des Detektors und werden nicht rückwirkend neu klassifiziert.

> [!NOTE]
>
> Dies ist ein konservatives zusätzliches Signal, keine vollständige Erkennung von synthetischen Medien oder eingeschleustem Video. Eine Aufzeichnung ohne Auffälligkeiten ist kein Beweis für Liveness. Kurze oder uneindeutige Aufnahmen sowie Aufnahmen ohne verwertbare Replay-Nachweise bleiben von dieser Prüfung unmarkiert. Fehlende oder unlesbare Aufzeichnungen erzeugen keinen Befund aus dieser Prüfung; andere Verifizierungsprüfungen gelten weiterhin.

### Sitzungsübergreifender Gesichtsabgleich

| Risiko | Ursache | Zusätzliche Daten | Schweregrad |
| - | - | - | - |
| `FACE_IN_BLOCKLIST` | Gesicht stimmte mit einem Gesicht auf der Sperrliste überein. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `error` – **automatische Ablehnung** |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Gesicht stimmte in einem Bereich geringerer Konfidenz mit einem Gesicht auf der Sperrliste überein. | `blocklisted_session_id`, `blocklisted_session_number`, `api_service` | `warning` – in Workflows immer an Review weitergeleitet |
| `FACE_IN_ALLOWLIST` | Gesicht stimmte mit einem Gesicht auf der Positivliste überein. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` – Aktion für doppeltes Gesicht übersprungen |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Gesicht stimmte in einem Bereich geringerer Konfidenz mit einem Gesicht auf der Positivliste überein. | `allowlisted_session_id`, `allowlisted_session_number`, `api_service` | `information` – Aktion für mögliches doppeltes Gesicht übersprungen |
| `DUPLICATED_FACE` | Gesicht stimmte mit einem bereits genehmigten Gesicht eines anderen Benutzers überein (eine `Approved`-Sitzung mit abweichenden `vendor_data` oder ein für einen Ihrer Vendor-Benutzer importiertes Gesicht). | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Konfigurierbar – standardmäßig `information` |
| `POSSIBLE_DUPLICATED_FACE` | Gesicht stimmte in einem Bereich geringerer Konfidenz mit einem anderen genehmigten oder importierten Gesicht überein. | `duplicated_session_id`, `duplicated_session_number`, `api_service` | Konfigurierbar – standardmäßig `information` |
| `DUPLICATED_FACE_NAME_MISMATCH` | Wird zusammen mit `DUPLICATED_FACE` ausgegeben, wenn die Identität der übereinstimmenden Sitzung nicht mit dem aufgelösten Namen dieser Sitzung übereinstimmt (Ausweisdokument, `expected_details` oder verknüpfter Vendor-Benutzer), wobei dasselbe Name-Match-Scoring und derselbe Schwellenwert wie bei der Ausweisverifizierung verwendet werden. Ein unter einem anderen Namen wiederverwendetes Gesicht ist ein stärkeres Betrugssignal als ein einfaches Duplikat und verfügt daher über eine eigene konfigurierbare Aktion. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | Konfigurierbar – standardmäßig `warning`. Schwächt das für `DUPLICATED_FACE` konfigurierte Ergebnis niemals ab, sondern eskaliert es nur. |
| `DUPLICATED_FACE_DOCUMENT_MISMATCH` | Wird zusammen mit `DUPLICATED_FACE` ausgegeben, wenn das Ausweisdokument des übereinstimmenden Benutzers ein anderes Geburtsdatum aufweist als das Dokument dieser Sitzung. Dieselbe Person, die ein anderes Dokument (beispielsweise einen Reisepass nach einem Personalausweis) oder ein erneuertes Dokument vorlegt, wird nicht markiert, und zwei Sitzungen mit derselben Dokumentennummer aus demselben Land werden niemals markiert. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `mismatch_dimensions` | Konfigurierbar (`face_liveness_duplicated_face_document_mismatch_action`) – standardmäßig `Review`. Schwächt das für `DUPLICATED_FACE` konfigurierte Ergebnis niemals ab, sondern eskaliert es nur. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Gesicht stimmt mit einem Gesicht aus einer früheren Sitzung dieser Anwendung eines anderen Benutzers überein, dessen eigene Liveness-Erfassung mit hoher Konfidenz als Angriff eingestuft wurde. Ein Anhaltspunkt zur Prüfung, kein Beweis für einen Angriff. | `liveness_attack_session_id`, `liveness_attack_session_number`, `similarity_percentage`, `liveness_attack_sessions_count` | Konfigurierbar – standardmäßig `information` (keine Aktion) |

Bei Übereinstimmungen mit importierten Gesichtern oder Listeneinträgen (die keine Sitzung haben) sind die Werte `*_session_id`, `*_session_number` und `api_service` in `additional_data` jeweils `null`.

Gesichter desselben Benutzers (gleiche `vendor_data` oder derselbe Vendor-Benutzer, falls verfügbar) werden von der **gesamten** Indexsuche ausgeschlossen – sowohl von der Duplikaterkennung als auch vom Sperrlisten-Screening. Die Rangfolge bei Übereinstimmungen lautet: Sperrliste exakt → Positivliste exakt → Duplikat exakt → Sperrliste möglich → Positivliste möglich → Duplikat möglich – pro Bericht wird nur einer dieser sechs sich gegenseitig ausschließenden Codes ausgegeben. `DUPLICATED_FACE_NAME_MISMATCH` gehört nicht zu dieser Vorranggruppe: Es handelt sich um einen zusätzlichen Code, der **zusätzlich zu** `DUPLICATED_FACE` ausgegeben wird, wenn auch die Identitätsprüfung fehlschlägt, und niemals an dessen Stelle. `additional_data.name_match_score` enthält niemals die verglichenen Namen – nur IDs und einen Übereinstimmungswert, sodass keine personenbezogenen Daten (PII) in der Payload der Warnung landen.

Ein Name, der auf jedem Dokument in einem anderen Schriftsystem geschrieben ist (beispielsweise hebräisch auf dem einen und lateinisch auf dem anderen), kann den Schwellenwert unterschreiten, selbst wenn beide Sitzungen derselben Person gehören. In diesem einen Fall wird `DUPLICATED_FACE_NAME_MISMATCH` nicht ausgegeben, wenn sich die Ausweisdokumente beider Sitzungen in allen folgenden Punkten gegenseitig bestätigen:

* Beide Dokumente weisen denselben Ausstellungsstaat auf.
* Ein Identifikator stimmt zwischen beiden Dokumenten exakt überein. `document_number` und `personal_number` können gleichwertig verwendet werden, da dieselbe nationale Kennnummer je nach Dokumenttyp in jedem der beiden Felder stehen kann.
* Sofern beide Dokumente ein Geburtsdatum enthalten, handelt es sich um dasselbe Datum.

Wenn die Namen im selben Schriftsystem vorliegen, wenn sich der Identifikator oder der Ausstellungsstaat unterscheidet oder fehlt oder wenn sich die Geburtsdaten widersprechen, wird die Warnung dennoch wie oben beschrieben ausgegeben.

### Qualität der passiven Liveness-Erkennung (nur bei `method = "PASSIVE"`)

| Risiko | Ursache | Schweregrad | Behebung |
| - | - | - | - |
| `MULTIPLE_FACES_DETECTED` | Während der Erfassung war mehr als ein Gesicht sichtbar. Für das Scoring und den Abgleich wird immer das größte Gesicht verwendet. | Konfigurierbar – standardmäßig `information` | Alleine erneut aufnehmen. |
| `LOW_FACE_QUALITY` | Gesichtsqualität liegt unter dem Prüfungsschwellenwert (Standardwert 15). | `warning`; `error`, wenn unter dem Ablehnungsschwellenwert (Standardwert 0 – Ablehnung deaktiviert) | Bessere Schärfe / weniger Verdeckung / zentriertes Gesicht. |
| `LOW_FACE_LUMINANCE` | Normalisierte Helligkeit unter dem Mindestschwellenwert (Standardwert 20). | Konfigurierbar – standardmäßig `warning` (Aktion standardmäßig Review) | Bessere Beleuchtung. |
| `HIGH_FACE_LUMINANCE` | Normalisierte Helligkeit über dem Maximalschwellenwert (Standardwert 80). | Konfigurierbar – standardmäßig `warning` (Aktion standardmäßig Review) | Beleuchtung reduzieren; Gegenlicht vermeiden. |

`LOW_FACE_LUMINANCE` und `HIGH_FACE_LUMINANCE` schließen sich gegenseitig aus – die Helligkeit liegt entweder unter dem Minimum oder über dem Maximum, niemals beides.

### Altersschätzung (adaptive Workflows und `AGE_ESTIMATION`-Knoten)

| Risk | Cause | Severity | Remediation |
| - | - | - | - |
| `AGE_BELOW_MINIMUM` | Das geschätzte Alter liegt unter dem konfigurierten Minimum (oder dem Grenzwert für Grenzfälle, wenn der Fallback auf die Ausweisverifizierung aktiviert ist). | `error` | Der Workflow fällt auf die Ausweisverifizierung zurück, sofern konfiguriert. |
| `AGE_NOT_DETECTED` | Das Alter konnte nicht geschätzt werden und der Fallback auf die Ausweisverifizierung ist deaktiviert. | `error` | Aktivieren Sie den Fallback oder führen Sie die Erfassung erneut durch. |

## Exakte Beschreibungsstrings

Die API gibt für jedes Risiko exakt diese `short_description`- und `long_description`-Zeichenfolgen zurück:

| `risk` | `short_description` | `long_description` |
| - | - | - |
| `NO_FACE_DETECTED` | Kein Gesicht während der Liveness erkannt | Das System konnte während der Liveness-Prüfung kein Gesicht identifizieren, was auf eine schlechte Bildqualität, eine fehlerhafte Positionierung oder technische Probleme zurückzuführen sein kann. |
| `LIVENESS_FACE_ATTACK` | Liveness-Gesichtsangriff | Das System hat einen potenziellen Versuch erkannt, die Liveness-Prüfung zu umgehen. |
| `LOW_LIVENESS_SCORE` | Niedriger Liveness-Score | Die Liveness-Prüfung führte zu einem niedrigen Score, was auf die potenzielle Verwendung nicht lebensechter Gesichtsdarstellungen oder biometrische Daten von geringer Qualität hinweist. |
| `LIVENESS_VIDEO_ANOMALY` | Liveness-Videostream-Anomalie | Das aufgezeichnete Liveness-Video enthält eine wiederholte Bewegungssequenz, die auf einen Feed in Schleife hinweist. Kamera-Stillstände, wiederholte Standbilder und eine langsame Bildbereitstellung allein lösen dieses Signal nicht aus. Dies ist eine unabhängige Aufzeichnungsprüfung, keine vollständige Bewertung darüber, ob die Erfassung live ist. |
| `FACE_IN_BLOCKLIST` | Gesicht auf Sperrliste | Das System hat ein Gesicht auf der Sperrliste identifiziert; dieses Gesicht darf daher nicht verifiziert werden. |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Mögliches Gesicht auf Sperrliste | Das System hat ein mögliches Gesicht auf der Sperrliste identifiziert; dieses Gesicht darf daher nicht verifiziert werden. |
| `FACE_IN_ALLOWLIST` | Gesicht auf Positivliste | Das Gesicht stimmte mit der Gesichts-Positivliste der Anwendung überein, daher wurden Aktionen für doppelte Gesichter für dieses Signal übersprungen. |
| `POSSIBLE_FACE_IN_ALLOWLIST` | Mögliches Gesicht auf Positivliste | Das Gesicht stimmte möglicherweise mit der Gesichts-Positivliste der Anwendung überein, daher wurden Aktionen für potenziell doppelte Gesichter für dieses Signal übersprungen. |
| `DUPLICATED_FACE` | Doppeltes Gesicht aus anderer genehmigter Sitzung | Das System hat ein doppeltes Gesicht aus einer anderen genehmigten Sitzung identifiziert, was weitere Untersuchungen erfordert. |
| `POSSIBLE_DUPLICATED_FACE` | Mögliches doppeltes Gesicht aus anderer genehmigter Sitzung | Das System hat ein möglicherweise doppeltes Gesicht aus einer anderen genehmigten Sitzung identifiziert, was weitere Untersuchungen erfordert. |
| `DUPLICATED_FACE_NAME_MISMATCH` | Doppeltes Gesicht unter anderem Namen | Dasselbe Gesicht wurde bereits in einer anderen Sitzung genehmigt, jedoch unter einem anderen Namen. Die Identität hinter dem Duplikat stimmt nicht mit der für diese Sitzung angegebenen Identität überein, was ein starker Indikator für Identitätsbetrug ist. |
| `FACE_MATCHES_LIVENESS_ATTACK` | Gesicht stimmt mit einem Liveness-Angriff überein | Das Gesicht in dieser Liveness-Erfassung stimmt mit einem Gesicht aus einer früheren Sitzung dieser Anwendung überein. Die eigene Erfassung dieses Gesichts gehörte zu einer Sitzung eines anderen Benutzers und wurde von der Liveness-Engine mit hoher Konfidenz als Angriff eingestuft. Ein echter Benutzer kann versehentlich abgelehnt werden, daher ist dies ein Signal zur Prüfung und kein Beweis für einen Angriff. |
| `MULTIPLE_FACES_DETECTED` | Mehrere Gesichter erkannt | Im Liveness-Bild wurden mehrere Gesichter erkannt. Das System verwendet das größte Gesicht für die Liveness-Verifizierung und den Gesichtsabgleich, aber das Vorhandensein mehrerer Gesichter erfordert möglicherweise eine zusätzliche Prüfung. |
| `LOW_FACE_QUALITY` | Geringe Gesichtsqualität | Die Qualität des Gesichtsbildes liegt unter dem akzeptablen Schwellenwert, was die Zuverlässigkeit der Liveness-Erkennung beeinträchtigen kann. Dies kann an der Kameraauflösung, dem Fokus oder Kompressionsartefakten liegen. |
| `LOW_FACE_LUMINANCE` | Geringe Gesichtsleuchtdichte | Das Gesichtsbild ist zu dunkel, was die Genauigkeit der Liveness-Erkennung beeinträchtigen kann. Bessere Lichtverhältnisse werden empfohlen. |
| `HIGH_FACE_LUMINANCE` | Hohe Gesichtsleuchtdichte | Das Gesichtsbild ist zu hell oder überbelichtet, was die Genauigkeit der Liveness-Erkennung beeinträchtigen kann. Weniger Licht oder das Vermeiden von direktem Licht wird empfohlen. |
| `AGE_BELOW_MINIMUM` | Alter unter dem Minimum | Das Alter des Gesichts liegt unter dem Schwellenwert für das Mindestalter der Anwendung. |
| `AGE_NOT_DETECTED` | Alter nicht erkannt | Das System konnte das Alter des Gesichts nicht ermitteln, was für die Dokumentenverifizierung erforderlich ist. |

## Standalone-API für passive Liveness

Die Standalone-[Liveness-API](https://docs.didit.me/de/standalone-apis/passive-liveness.md) greift auf dieselben Risiko-Codes zurück, weist jedoch einige Verhaltensunterschiede auf:

* `NO_FACE_DETECTED` und `LOW_LIVENESS_SCORE` schließen sich gegenseitig aus – die Score-Prüfung wird nur ausgeführt, wenn ein Gesicht gefunden wurde. `LOW_LIVENESS_SCORE` greift gegen den `face_liveness_score_decline_threshold` der Anfrage (Standardwert 30) und enthält immer `log_type: "error"`.
* `POSSIBLE_FACE_IN_BLOCKLIST` wird als Ablehnung (`log_type: "error"`) statt als Prüfung behandelt.
* `MULTIPLE_FACES_DETECTED` enthält `log_type: "warning"`, während die Risiken für doppelte Gesichter informativ bleiben. Nur Warnungen der Stufe `error` setzen den `status` der Standalone-Antwort auf `Declined`.
* Standalone-Warnungseinträge enthalten `feature`, aber keine `node_id`.

## Beispiele

### Automatisches Ablehnen bei erkanntem Angriff

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]
```

### Konfigurierbare Warnungen bei einer passiven Erfassung

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "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.",
    "node_id": "liveness_primary"
  }
]
```

### Dupliziertes Gesicht mit Payload

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

Hier ist die Aktion für duplizierte Gesichter auf Überprüfung eingestellt, sodass die Warnung `log_type: "warning"` enthält und der Status des Liveness-Berichts `In Review` lautet. Mit dem Standardwert (Keine Aktion) würde sie stattdessen `log_type: "information"` enthalten. `api_service` ist `null`, da das übereinstimmende Gesicht aus einer Workflow-Sitzung und nicht aus einem eigenständigen API-Aufruf stammt.

### Dupliziertes Gesicht unter einem anderen Namen

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "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.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE` verbleibt bei seiner eigenen konfigurierten Aktion (hier: Keine Aktion – `log_type: "information"`), während `DUPLICATED_FACE_NAME_MISMATCH` seine eigene Aktion trägt, standardmäßig Überprüfung (`log_type: "warning"`). Der Status des Liveness-Berichts richtet sich nach dem schwerwiegenderen der beiden: hier `In Review`, obwohl die einfache Einstellung für duplizierte Gesichter allein dies nicht markiert hätte.

### Plausibilitätsanomalie der Aufnahme mit ihren Messwerten

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

Dieses Beispiel zeigt die Replay-Nachweise aus einer Aufnahme, die drei Kopien einer bewegten Sequenz enthält. `log_type` ist `information`, da die konfigurierte Aktion `NO_ACTION` lautet. Die Diagnostik zur Frame-Zustellung, die in diesem Beispiel aus Gründen der Übersichtlichkeit weggelassen wurde, löst den Befund nicht aus.

## Warnungstypen

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

## Verwandte Themen

* [Liveness-Bericht](https://docs.didit.me/de/core-technology/liveness/report-liveness.md) – vollständiges Berichtsschema und Statusangaben.
* [Warnungen beim Gesichtsabgleich](https://docs.didit.me/de/core-technology/face-match/warnings-face-match.md) – zugehörige Warnungen beim 1:1-Gesichtsabgleich.
* [Webhooks](https://docs.didit.me/de/integration/webhooks.md) – `session.status.updated` übermittelt die Warnungen, sobald der Liveness-Schritt abgeschlossen ist.
* [Datenmodelle – Liveness-Prüfung](https://docs.didit.me/de/reference/data-models.md#liveness-prüfung) – kanonisches Schema mit allen Feldern.
* [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.