> ## 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. # Adressnachweis: Warnungen und Fehlercodes > Alle Warncodes für den Adressnachweis bei Didit: Namensabweichung, abgelaufene Dokumente, Metadatenprobleme und automatische Ablehnungen. ## Übersicht Die Adressnachweis-Verifizierung (POA) gibt unter `poa_verifications[].warnings[]` Warnungen für jedes Qualitäts-, Authentizitäts- oder Abgleichsproblem aus, das während der Extraktion und forensischen Analyse erkannt wird. Jede Warnung ist ein [Warning-Objekt](https://docs.didit.me/de/reference/data-models.md#warnungsobjekt), bei dem `feature` auf `"PROOF_OF_ADDRESS"` gesetzt ist. Eine Handvoll Risiken erzwingt immer den Status `Declined`; die übrigen folgen einer pro Risiko konfigurierten Aktion (`DECLINE` / `REVIEW` / `NO_ACTION`) in Ihrem Workflow. Jedes der folgenden Risiken wird anhand der Live-Entscheidungspipeline verifiziert; die exakten kurzen und langen Beschreibungstexte sind in den Tabellen wortgetreu wiedergegeben. > [!NOTE] > > Die POA-Extraktion führt zu einer Latenz von **5–15 Sekunden** pro Dokument. Warnungen werden erst geschrieben, wenn der Workflow-Schritt abgeschlossen ist; führen Sie Abfragen nicht häufiger als alle 5 s durch. ## Zwei Produktionspfade POA-Warnungen werden auf zwei verschiedenen Pfaden erzeugt, und das Risikoset unterscheidet sich zwischen beiden: * **Workflow-Sitzungen** (der POA-Schritt innerhalb einer Verifizierungssitzung) – der Upload-Endpoint führt zunächst eine blockierende Validierung mit einer Wiederholungsschleife aus (siehe [Wiederholungsverhalten](#verhalten-bei-wiederholungsversuchen-workflow-sitzungen)), danach werden die endgültig gespeicherten Warnungen durch `check_poa_risks` plus den dokumentenübergreifenden Namensabgleich berechnet. * **Eigenständige API** (`POST /v3/poa/`) – Warnungen stammen ausschließlich aus `check_poa_risks`. Es gibt weder eine Wiederholungsschleife noch einen Kontext zu einem verifizierten Ausweis und nur ein einziges Dokument, sodass `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED` und `FUTURE_ISSUE_DATE` von der eigenständigen API **nie** erzeugt werden. Die Validierungsfehler vor der Extraktion werden auf diesem Pfad verworfen. `POOR_DOCUMENT_QUALITY` ist im Risk-Enum definiert und im Action-Mapping reserviert, wird jedoch **von keinem Codepfad in der POA-Pipeline erzeugt** – es erscheint auf keinem der beiden Pfade in `warnings[]`. Führen Sie darauf keine Verzweigungen aus. ## Warnungen mit automatischer Ablehnung (erzwingen immer `Declined`) Diese Risiken sind in `AUTO_DECLINE_RISKS` enthalten; wenn sie protokolliert werden, lautet der POA-Status unabhängig von der Konfiguration `Declined`, und `log_type` ist immer `error`. | Risiko | Ursache | Empfohlene Behebung | | - | - | - | | `MISSING_ADDRESS_INFORMATION` | Aus dem Dokument konnte keine Adresse extrahiert werden. | Bitten Sie den Benutzer, ein Dokument erneut einzureichen, auf dem seine Adresse deutlich zu sehen ist. | | `POA_DOCUMENT_EXPIRED` | Das Dokument ist über einen von zwei Pfaden abgelaufen: Sein **gedrucktes Ablaufdatum** ist überschritten oder es ist **älter als das konfigurierte Höchstalter** für seinen Typ. Standardwerte: **3 Monate** für `UTILITY_BILL` und `BANK_STATEMENT`, **12 Monate** für `GOVERNMENT_ISSUED_DOCUMENT` und `OTHER_POA_DOCUMENT` (ein Monat zählt als 30 Tage; `-1` deaktiviert die Prüfung). `additional_data` enthält immer `expiration_reason` (`printed_expiration` oder `age_window`), `document_type`, `document_subtype` und `issue_date`; der Pfad `printed_expiration` fügt `expiration_date` hinzu und der Pfad `age_window` fügt `max_age_months` hinzu. | Bitten Sie den Benutzer um ein gültiges oder aktuelleres Dokument oder erhöhen Sie `age_months` für diesen Typ. | | `INVALID_DOCUMENT_TYPE` | Das Dokument konnte keinem unterstützten POA-Typ zugeordnet werden (`document_type` fällt auf `UNKNOWN` zurück). | Bitten Sie den Benutzer um eine erneute Einreichung; prüfen Sie, ob die Datei beschädigt ist. | | `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | Die Prüfung des Dokumentenalters selbst ist fehlgeschlagen (Fehler bei der Berechnung des Ablaufdatums anhand des Ausstellungsdatums). | Bitten Sie den Benutzer um ein Dokument mit einem deutlich lesbaren Ausstellungsdatum. | `FUTURE_ISSUE_DATE` ist ebenfalls in `AUTO_DECLINE_RISKS` aufgeführt, hat jedoch einen einzigen Erzeuger in der Validierung vor der Extraktion (ein Ausstellungsdatum, das mehr als 7 Tage in der Zukunft liegt), dessen Fehler ausschließlich in die **Workflow-Wiederholungsschleife** einfließen – es tritt dort als blockierender Upload-Fehler auf, wird von der eigenständigen API nie erzeugt und wird nicht in `warnings[]` geschrieben. Siehe [Wiederholungsverhalten](#verhalten-bei-wiederholungsversuchen-workflow-sitzungen). ## Konfigurierbare Warnungen Jede dieser Warnungen richtet sich nach einer Aktionseinstellung am POA-Knoten des Workflows (`DECLINE` / `REVIEW` / `NO_ACTION`). Der `log_type` der Warnung entspricht der konfigurierten Aktion: `error` bei Ablehnen, `warning` bei Prüfung, `information` bei keiner Aktion. | Risiko | Ursache | Aktionseinstellung | Standard | | - | - | - | - | | `NAME_MISMATCH_WITH_PROVIDED` | Der Name auf dem Dokument erreicht bei einem Abgleich mit dem Namen, der bei der Sitzungserstellung angegeben wurde (`expected_details`), keinen Wert von mindestens `poa_name_match_score_threshold` (Standard 86). | `poa_name_or_address_mismatch_action` | Prüfung | | `NAME_MISMATCH_ID_VERIFICATION` | Der Name auf dem Dokument erreicht bei einem Abgleich mit dem verifizierten Ausweisdokument keinen Schwellenwert. `additional_data`: `{ poa_name, kyc_name, match_score }`. Nur für Workflow-Sitzungen. | `poa_name_or_address_mismatch_action` | Prüfung | | `ADDRESS_MISMATCH_WITH_PROVIDED` | Die extrahierte Adresse weicht von der per API übermittelten Adresse ab, oder eine der beiden Adressen konnte nicht als Wohnadresse verifiziert werden. | `poa_name_or_address_mismatch_action` | Prüfung | | `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | Das Land des Dokuments stimmt nicht mit dem per API übermittelten Land überein (ISO-3-normalisiert). `additional_data`: `{ expected_country, extracted_country }`. | `poa_name_or_address_mismatch_action` | Prüfung | | `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Zwei oder mehr Adressnachweise in derselben Sitzung enthalten unterschiedliche Namen. `additional_data` enthält beide Knoten-IDs, beide Namen und den Übereinstimmungswert. Nur für Workflow-Sitzungen. | `poa_name_or_address_mismatch_action` | Prüfung | | `DOCUMENT_METADATA_MISMATCH` | Die Datei ist leer (`file_size` 0) oder ihre EXIF-Datumsangaben sind fehlerhaft. | `poa_document_issues_action` | Prüfung | | `SUSPECTED_DOCUMENT_MANIPULATION` | Die Forensik hat Hinweise auf eine Manipulation gefunden: Änderung nach der digitalen Signatur (`is_tampered`), Manipulation von Overlay-Text (mit Rechtecken in `additional_data.manipulated_regions`), ein bekannter PDF-Editor, inkonsistente EXIF-Datumsangaben oder ein verdächtiges erneutes Exportieren. `additional_data.detection_method` benennt die Prüfung, die angeschlagen hat. | `poa_document_authenticity_action` | **Ablehnen** | | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Ein Textfeld wurde geleert und in einer anderen Schriftart neu geschrieben, und die Datei enthält keinen Nachweis, ob sich der Inhalt geändert hat: Online-Editoren schreiben auch unveränderten Text neu. Diese Warnung löst allein nie `SUSPECTED_DOCUMENT_MANIPULATION` aus. Löst ein anderes Signal bei demselben Dokument diesen Risikotyp aus, entscheidet die strengere der beiden Aktionen. `additional_data.detection_method` ist `unproven_text_replacement`, mit `replaced_text` und `manipulated_regions`. Auch eine Datei, die nicht vollständig geprüft werden konnte, löst diese Warnung aus, weil der nicht geprüfte Teil ein solches Feld enthalten könnte: `detection_method` ist dann `analysis_incomplete`, mit leeren `replaced_text` und `manipulated_regions`, sofern im geprüften Teil kein Feld gefunden wurde. | `poa_document_unproven_text_replacement_action` | Prüfung | | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Die Sprache des Dokuments ist nicht in `poa_languages_allowed` enthalten. | `poa_unsupported_language_action` | **Ablehnen** | | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Der erkannte Dokumenttyp ist für das Land des Dokuments nicht in `poa_documents_allowed` aktiviert, oder sein Untertyp ist ausdrücklich deaktiviert. | `poa_unsupported_document_type_action` | **Ablehnen** | | `ISSUER_NOT_IDENTIFIED` | Die ausstellende Institution konnte anhand des Dokuments nicht identifiziert werden. | `poa_issuer_not_identified_action` | Prüfung | | `UNABLE_TO_EXTRACT_ISSUE_DATE` | Auf dem Dokument konnte kein gültiges Ausstellungsdatum gefunden werden. | `poa_issue_date_not_detected_action` | Prüfung | | `POA_NAME_NOT_DETECTED` | Auf dem Dokument wurde kein Name erkannt. | `poa_issue_date_not_detected_action` (gemeinsame Einstellung) | Prüfung | | `UNPARSABLE_OR_INVALID_ADDRESS` | Eine Adresse wurde extrahiert, konnte aber nicht geparst und geocodiert werden, sodass keine gültige Wohnadresse entstand. | `poa_unparsable_or_invalid_address_action` | Prüfung | | `POA_MAX_ATTEMPTS_EXCEEDED` | Der Benutzer hat `poa_max_retry_attempts` (Standard 2) in der Wiederholungsschleife des Workflows ausgeschöpft. `additional_data`: `{ attempts }`. Nur für Workflow-Sitzungen. | `poa_max_attempts_exceeded_action` | **Ablehnen** | > [!NOTE] > > Für alle Namens- und Adressabweichungen gibt es **eine gemeinsame Aktion**: `poa_name_or_address_mismatch_action` deckt beide Namensrisiken, beide Adressrisiken und die dokumentübergreifende Namensprüfung ab. Namens- und Adressabweichungen lassen sich nicht getrennt konfigurieren. Bei der eigenständigen API folgt dieselbe Gruppe der Anfrage-Option `poa_address_mismatch_action` (die Option `poa_name_mismatch_action` wird akzeptiert, aber nie ausgelesen). ## Unterschiede der Standalone-API (`POST /v3/poa/`) Der Standalone-Endpoint bildet dieselbe Zuordnung von Risiken zu Aktionen ab, jedoch mit Optionen auf Anfrageebene, die nur `DECLINE` oder `NO_ACTION` akzeptieren (alle standardmäßig auf `DECLINE` gesetzt): * `UNABLE_TO_EXTRACT_ISSUE_DATE` und `POA_NAME_NOT_DETECTED` sind an diesem Endpoint **fest auf Ablehnen gesetzt**. * `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` und `UNPARSABLE_OR_INVALID_ADDRESS` sind hier **informativ** – ihre Aktionen sind standardmäßig auf Keine Aktion gesetzt und können nicht pro Anfrage konfiguriert werden. * `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` und `POA_MAX_ATTEMPTS_EXCEEDED` werden nie erzeugt – ein Dokument mit einem Datum in der Zukunft wird an diesem Endpoint **nicht** automatisch abgelehnt. Siehe die [POST /v3/poa/ API-Referenz](https://docs.didit.me/de/standalone-apis/proof-of-address.md) für die Anfrageoptionen. ## Verhalten bei Wiederholungsversuchen (Workflow-Sitzungen) In einer Verifizierungssitzung führt der POA-Upload-Schritt eine blockierende Validierung durch, bevor das Dokument akzeptiert wird. Wenn dabei ein blockierender Fehler festgestellt wird – `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE` oder `POA_DOCUMENT_EXPIRED` –, wird der Upload mit `400` und dem Risiko-Code als Nachricht abgelehnt, und der Benutzer kann es mit einem besseren Dokument erneut versuchen. Bei `POA_DOCUMENT_EXPIRED` enthält der `400`-Body außerdem `expiration_reason` (`printed_expiration` oder `age_window`), sodass Ihre Benutzeroberfläche den genauen Grund anzeigen kann; beim Pfad `age_window` ist zusätzlich `max_age_months` enthalten. Beim Pfad `printed_expiration` wird `max_age_months` bewusst weggelassen, da das Dokument aufgrund seines aufgedruckten Ablaufdatums und nicht wegen eines Altersfensters abgelehnt wurde. Sobald der Benutzer `poa_max_retry_attempts` Versuche verbraucht hat (Standardwert 2, konfigurierbar von 2–5), wird die Übermittlung trotzdem akzeptiert: Die gespeicherten Warnungen werden anhand des gespeicherten Dokuments neu berechnet, `POA_MAX_ATTEMPTS_EXCEEDED` wird angehängt und der Status wird anhand des vollständigen Risikosatzes ermittelt. Aus diesem Grund kann `FUTURE_ISSUE_DATE` einen Upload blockieren, erscheint jedoch nie in `warnings[]`. ## Konfigurierbare Einstellungen Der POA-Knoten des Workflows stellt diese Stellschrauben bereit (entsprechend den Feldern in `VerificationSettings`): | Einstellung | Steuert | Standard | | - | - | - | | `poa_name_or_address_mismatch_action` | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Review | | `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Review | | `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Decline | | `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Review (ein Workflow, der nie prüft, verwendet seine eigene `poa_document_authenticity_action`, wenn diese Decline ist, andernfalls No action; die Standalone-API folgt der `poa_document_authenticity_action` der Anfrage) | | `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Decline | | `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Decline | | `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Review | | `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Review | | `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Review | | `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Decline | | `poa_documents_allowed` | Für jedes Land akzeptierte Dokumenttypen, jeweils mit `enabled` und `age_months` (`-1` = unbegrenzt); Überschreibungen pro Untertyp über `document_subtypes_config`. | Verbrauchsabrechnung und Kontoauszug: 3 Monate; behördlich ausgestellte und sonstige Dokumente: 12 Monate | | `poa_languages_allowed` | Akzeptierte Dokumentensprachen. | Alle unterstützten Sprachen | | `poa_name_match_score_threshold` | Mindestübereinstimmungswert für den Namensabgleich (0–100), bevor die `NAME_MISMATCH*`-Risiken ausgelöst werden. | 86 | | `poa_max_retry_attempts` | Upload-Versuche, bevor die Wiederholungsschleife abbricht (2–5). | 2 | ## Logik für den Namensabgleich Der POA-Namensabgleich toleriert gängige Variationen: * **Zweitnamen und Initialen** werden tolerant abgeglichen (Vorhandensein/Fehlen ist zulässig). * **Kandidatennamen** – Jeder auf dem Dokument erkannte Name (`name_on_document` zuzüglich `additional_names`) wird bewertet, und der Kandidat mit dem höchsten Übereinstimmungswert wird beibehalten. * **Übereinstimmungs-Schwellenwert** – Der Standardwert für `poa_name_match_score_threshold` ist **86**; ein Wert darunter löst die entsprechende `NAME_MISMATCH*`-Warnung aus. Die numerischen Übereinstimmungswerte werden im Bericht als `name_match_score_expected_details` und `name_match_score_id_verification` (0–100) ausgewiesen. Diese Werte sind nützlich für eine detaillierte Prüfung, selbst wenn keine Warnung ausgelöst wurde. ## Beispiele ### Overlay-Manipulation (standardmäßig: Ablehnung) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "SUSPECTED_DOCUMENT_MANIPULATION", "additional_data": { "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).", "detection_method": "overlay_text_manipulation", "signals": ["duplicate_font_subset", "glyph_fragmentation"], "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }], "fragmented_fonts": [], "manipulated_regions": [ { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 } ] }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential document manipulation or editing.", "node_id": "feature_poa_1" } ] } ``` ### Abgelaufenes Dokument + fehlende Adresse (automatische Ablehnung) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "POA_DOCUMENT_EXPIRED", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "ELECTRICITY_BILL", "document_type": "UTILITY_BILL", "issue_date": "2025-11-02" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.", "node_id": "feature_poa_1" }, { "feature": "PROOF_OF_ADDRESS", "risk": "MISSING_ADDRESS_INFORMATION", "additional_data": null, "log_type": "error", "short_description": "Missing address information", "long_description": "The document does not contain complete or clear address information that can be extracted.", "node_id": "feature_poa_1" } ] } ``` ### Namensabweichung (standardmäßig Prüfung) ```json theme={null} { "warnings": [ { "feature": "PROOF_OF_ADDRESS", "risk": "NAME_MISMATCH_ID_VERIFICATION", "additional_data": { "poa_name": "JOHN B SMYTH", "kyc_name": "John A. Smith", "match_score": 60 }, "log_type": "warning", "short_description": "Name mismatch with ID verification", "long_description": "The full name on the document does not match the name from the user's verified identity documents.", "node_id": "feature_poa_1" } ] } ``` ## Verwandte Themen * [Adressnachweis-Bericht](https://docs.didit.me/de/core-technology/proof-of-address/report-proof-of-address.md) – Vollständige Antwortstruktur, Forensik bei Overlay-Manipulation, Statussemantik * [Adressnachweis – Übersicht](https://docs.didit.me/de/core-technology/proof-of-address/overview.md) – Akzeptierte Dokumenttypen * [Datenmodelle – Adressnachweis](https://docs.didit.me/de/reference/data-models.md#adressnachweis) – Kanonisches Schema und Warnungsobjekt * [Webhooks](https://docs.didit.me/de/integration/webhooks.md) – `status.updated` übermittelt POA-Warnungen ### Warnungstypen This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.