API-Fehler in Didit: Statuscodes, Antworten und Behebung

Die Didit-API meldet Fehler mit einem HTTP-Statuscode und in fast jedem Fall mit einem JSON-Body. Diese Seite beschreibt, was die einzelnen Statuscodes bedeuten, wie der Body aufgebaut ist, nach welchen code-Werten Sie Verzweigungen vornehmen können und bei welchen Fehlern Wiederholungsversuche sicher sind. Verlassen Sie sich primär auf den Statuscode und auf code, sofern vorhanden, da sich der Text einer Nachricht ändern kann.

Statuscodes

Status	Bedeutung	Was zu tun ist	Wiederholen?
`400`	Die Anfrage ist ungültig: Ein Feld hat die Validierung nicht bestanden oder ein Bild oder Dokument konnte nicht gelesen werden	Beheben Sie, was im Body angegeben ist	Nach Behebung
`401`	Der übermittelte Schlüssel ist falsch, fehlerhaft formatiert, widerrufen oder abgelaufen	Überprüfen Sie `DIDIT_API_KEY` oder erstellen Sie einen neuen Schlüssel	Nach Behebung
`402`	Die Überprüfung konnte nicht bezahlt werden und wurde daher nicht ausgeführt	Laden Sie Ihr Guthaben auf	Nach dem Aufladen
`403`	Es wurde kein Schlüssel übermittelt, der Schlüssel hat keinen Zugriff auf diese Ressource oder Aktion, die Anfrage kam von außerhalb der IP-Liste des Schlüssels oder das Guthaben reicht für den Aufruf nicht aus	Lesen Sie den Body und sehen Sie unter Fehler bei API-Schlüsseln sowie Nicht genügend Credit nach	Nach Behebung
`404`	Die Ressource existiert nicht oder eine Sitzung liegt außerhalb der Workflows oder Status des Schlüssels	Überprüfen Sie die ID und die Einschränkungen des Schlüssels	Nein
`409`	Die Anfrage steht in Konflikt mit dem aktuellen Status, beispielsweise durch einen wiederverwendeten `Idempotency-Key` oder einen Schritt, der bereits ausgeführt wurde	Lesen Sie `code` aus und laden Sie den Status neu	Abhängig von `code`
`410`	Die Ressource ist abgelaufen, beispielsweise eine Sitzung oder eine Einladung	Erstellen Sie eine neue	Nein
`415`	Der Anfrage-Body ist kein JSON	Senden Sie `Content-Type: application/json`	Nach Behebung
`422`	Eine Adresse passt zu mehr als einer Blockchain, daher wurde nichts geprüft oder abgerechnet	Senden Sie die Anfrage erneut mit `blockchain` auf eine der `candidate_chains` gesetzt	Nach Behebung
`429`	Ein Rate-Limit oder ein Kontingent wurde erreicht	Warten Sie die Zeit aus `Retry-After` ab; siehe Rate-Limiting	Ja, nach Wartezeit
`500`	Ein unerwarteter Fehler aufseiten von Didit	Wiederholen Sie die Anfrage mit Backoff und kontaktieren Sie den Support, falls das Problem weiterhin besteht	Siehe Wiederholungsversuche
`502`	Ein Dienst, von dem Didit abhängt, hat einen Fehler zurückgegeben	Lesen Sie `code` aus	Siehe Wiederholungsversuche
`503`	Ein Dienst, von dem Didit abhängt, ist vorübergehend nicht verfügbar	Lesen Sie `code` aus und versuchen Sie es erneut	Siehe Wiederholungsversuche

Fehler-Bodys

Fehler-Bodys haben keine einheitliche Struktur, werten Sie sie daher defensiv aus. Der Aufbau hängt von der Endpoint-Familie ab:

Struktur	Wo sie auftritt	Beispiel
`detail`	Die meisten Fehler, einschließlich Fehlern bei der Authentifizierung, bei nicht gefundenen Ressourcen und bei Rate-Limits	`{"detail": "You do not have permission to perform this action."}`
`detail` und `code`	Fehler mit einem stabilen Code	`{"detail": "This application was deleted.", "code": "application_deleted"}`
Feldfehler	Eingabevalidierung	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	Feldübergreifende Validierung	`{"non_field_errors": ["..."]}`
Ein JSON-Array	Bestimmte Validierungsfehler, wie beispielsweise bei einem Simulate-Aufruf	`["Scenario can only be armed before the verification starts."]`
`error`	Die meisten eigenständigen APIs	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error` und `code`	Bildfehler bei eigenständigen APIs	`{"error": "...", "code": "invalid_image"}`
`error` als Code, mit `detail`	Digital-ID-Wallet-Verifizierung	`{"error": "insufficient_credits", "detail": "..."}`

Bei einem 500-Fehler wird unter Umständen gar kein JSON-Body zurückgegeben; fangen Sie daher Fälle ab, in denen der Body nicht geparst werden kann.

const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);

Fehler bei API-Schlüsseln

Was gesendet wurde	Status	`detail`
Kein `x-api-key`-Header	`403`	`You do not have permission to perform this action.`
Ein falscher, fehlerhaft formatierter oder widerrufener Schlüssel	`401`	`Authentication credentials were not provided or are invalid.`
Ein abgelaufener Schlüssel	`401`	`This API key has expired.`
Ein Schlüssel, der von außerhalb seiner IP-Liste verwendet wird	`403`	`This API key can't be used from this IP address.`
Ein berechtigungseingeschränkter Schlüssel ohne Zugriff auf diese Ressource oder Aktion	`403`	`This API key has no access to this endpoint.`
Ein auf bestimmte Workflows oder Status beschränkter Schlüssel an einem Endpoint, den er nicht nutzen kann	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
Ein auf bestimmte Workflows oder Status beschränkter Schlüssel bei einer Sitzung außerhalb dieser Grenzen	`404`	`Session not found.`
Ein Schlüssel, dessen Anwendung gerade gelöscht wurde	`403`	`This application was deleted.`, mit `"code": "application_deleted"`

Für einige Minuten nach dem Löschen einer Anwendung antwortet die API mit application_deleted, danach lehnt sie den Schlüssel wie jeden falschen Schlüssel ab. Führen Sie keinen Wiederholungsversuch durch: Die Anwendung und ihre Schlüssel existieren nicht mehr. Unter API-Authentifizierung und API-Schlüssel erfahren Sie, wie Schlüssel und deren Einschränkungen funktionieren.

Nicht genügend Credit

Jede API-Familie meldet ein unzureichendes Guthaben auf ihre eigene Weise:

Aufruf	Status	Body
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
Die meisten eigenständigen APIs	`403`	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`POST /v3/bank/account-check/`	`402`	`{"detail": "...", "code": "insufficient_credits"}`
Digital-ID-Wallet-Verifizierung	`403`	`{"error": "insufficient_credits", "detail": "..."}`
Transaktionen, Travel Rule und Adressvalidierung	`403`	`{"detail": "...", "code": "insufficient_credits"}`

Bei einem Vertrag antwortet das Erstellen einer Sitzung mit 403 und "code": "contract_billing_suspended", solange kostenpflichtige Dienste für Ihre Organisation pausiert sind. Sandbox-Anwendungen werden nie abgerechnet, daher überspringen sie diese Prüfungen.

Fehlercodes

Diese code-Werte sind stabil, sodass Sie darauf Verzweigungen aufbauen können. Die meisten befinden sich neben detail; bei der Digital-ID-Wallet-Verifizierung ist der Code der Wert von error.

Zugriff und Abrechnung

Code	Status	Bedeutung
`insufficient_credits`	`402`, `403`	Das Guthaben reicht für diesen Aufruf nicht aus
`contract_billing_suspended`	`403`	Kostenpflichtige Dienste sind für diese Organisation pausiert
`contract_rate_missing`	`402`, `403`	Im Vertrag ist für diese Prüfung kein Preis hinterlegt
`application_deleted`	`403`	Die Anwendung des Schlüssels wurde gelöscht
`organization_deleted`	`403`	Die Organisation des Schlüssels wurde gelöscht
`event_monitoring_disabled`	`403`	Die Erfassung von Ereignissen ist für diese Anwendung nicht aktiviert
`networks_not_entitled`	`403`	Betrugsnetzwerke sind für diese Organisation nicht freigeschaltet

Anfragen und Idempotenz

Code	Status	Bedeutung
`invalid_image`	`400`	Das Bild konnte nicht verwendet werden
`return_url_invalid`	`400`	Die Return-URL ist nicht zulässig
`idempotency_key_invalid`	`400`	Der `Idempotency-Key` ist länger als 255 Zeichen
`idempotency_key_reused`	`409`	Der Schlüssel wurde bereits mit einem anderen Body verwendet
`idempotency_key_in_progress`	`409`	Die erste Anfrage mit diesem Schlüssel wird noch ausgeführt; warten Sie auf `Retry-After`
`verification_in_progress`	`409`	Der Benutzer schließt diese Verifizierung gerade ab, daher kann sie nicht abgebrochen werden; warten Sie auf `Retry-After`
`feature_override_not_pending`	`409`	Der Override wurde bereits angewendet oder abgebrochen

Bank-, Telefon- und Risikoprüfungen

Code	Status	Bedeutung
`invalid_account_input`	`400`	Die Kontodaten sind ungültig
`country_not_covered`	`404`	Die Prüfung deckt dieses Land oder diese Art von Konto nicht ab
`bank_not_covered`	`404`	Die Prüfung unterstützt diese Bank nicht
`bank_verification_not_available`	`404`	Die Bankverifizierung ist nicht verfügbar
`account_check_unavailable`	`503`	Die Prüfung ist vorübergehend nicht verfügbar und die Anfrage wurde nicht berechnet
`phone_provider_unavailable`	`502`	Die Telefonverifizierung ist vorübergehend nicht verfügbar; es wird nichts abgerechnet und kein Versuch verbraucht
`risk_lookup_unavailable`	`502`	Die Risikoabfrage ist vorübergehend nicht verfügbar und die Anfrage wurde nicht berechnet

Unternehmensverifizierung (KYB)

Code	Status	Bedeutung
`kyb_registry_provider_unavailable`	`502`	Das Unternehmensregister ist vorübergehend nicht verfügbar
`kyb_registry_country_unsupported`	`400`	Die Registersuche deckt dieses Land nicht ab
`kyb_registry_search_limit_reached`	`429`	Die Anwendung hat ihr Limit von 600 kostenpflichtigen Suchanfragen pro Stunde erreicht
`kyb_session_not_writable`	`409`	Die Sitzung ist abgeschlossen
`kyb_step_mismatch`	`409`	Die Sitzung befindet sich in einem anderen Schritt; `next_step` gibt ihn an
`kyb_no_party_drafts`	`409`	Es liegen keine Entwürfe für Parteien zum Einreichen vor
`kyb_parties_already_submitted`	`409`	Die Parteien wurden bereits eingereicht
`kyb_party_kyc_session_not_deleted`	`409`	Die Verifizierung der Partei ist noch aktiv, daher kann sie nicht neu generiert werden

Digital-ID-Wallets

Code	Status	Bedeutung
`wallet_unavailable`	`403`	Diese Wallet ist für Ihre Anwendung nicht verfügbar
`wallet_provider_unavailable`	`502`	Die Wallet konnte nicht gestartet werden, und es wurde nichts erstellt
`wallet_not_configured`	`503`	Diese Umgebung kann die Wallet nicht erreichen

Berichte und Fälle

Code	Status	Bedeutung
`report_deletion_pending`	`409`	Der Bericht wird gelöscht; wiederholen Sie den Löschvorgang, um das Löschen seiner Dateien abzuschließen
`report_storage_unavailable`	`503`	Die Dateien des Berichts konnten nicht gelöscht werden; wiederholen Sie den Löschvorgang
`wallet_address_deletion_incomplete`	`503`	Eine gespeicherte Datei konnte nicht gelöscht werden, daher wurde der Löschvorgang gestoppt; versuchen Sie es erneut
`case_request_not_waiting`	`409`	Die Anfrage wartet nicht mehr auf den Kunden, daher gibt es nichts, woran er erinnert werden müsste
`case_request_reminder_too_soon`	`429`	Eine Erinnerung wurde kürzlich gesendet; `retry_at` gibt an, wann Sie die nächste senden können

E-Signaturen

Code	Status	Bedeutung
`signature_not_found`	`404`	Die Signatur existiert nicht
`signature_field_not_found`	`404`	Das Signaturfeld existiert nicht
`signature_not_signed`	`404`, `409`	Das Dokument wurde nicht signiert

Bei der Sitzungserstellung treten die folgenden Dokumentprobleme als Wert des betroffenen Felds mit dem Status 400 auf, zum Beispiel {"sign": "signature_document_changed"}:

Wert	Bedeutung
`signature_document_changed`	Das Dokument weicht von dem zuerst gesendeten ab
`signature_document_not_supported`	Das Dokumentformat wird nicht unterstützt
`signature_document_conversion_failed`	Das Dokument konnte nicht konvertiert werden
`field_anchor_not_found`	Der Textanker eines Felds wurde im Dokument nicht gefunden
`field_value_missing`	Ein Feld hat keinen Wert

Webhooks

Code	Status	Bedeutung
`webhook_url_missing`	`400`	Für die Zustellung ist keine URL hinterlegt, daher wird nichts gesendet
`invalid_webhook_payload`	`400`	Die Webhook-Daten haben kein gültiges Format
`webhook_resend_error`	`400`	Die gespeicherte Zustellung konnte nicht erneut signiert werden, oder der Versuch konnte nicht abgeschlossen werden

Wiederholungsversuche und Idempotenz

Manche Fehler können sicher wiederholt werden und manche nicht:

429: Warten Sie auf den Retry-After-Header und versuchen Sie es dann erneut.
502 und 503: Wiederholen Sie die Anfrage mit Backoff, wenn die Referenz des Endpoints besagt, dass nichts abgerechnet wurde, wie es bei Telefon-, E-Mail-, Bank- und Risikoprüfungen der Fall ist.
502 bei POST /v3/database-validation/: Lesen Sie zuerst jeden validation_errors-Eintrag, da dieser Status allein keinen vorübergehenden Fehler bedeutet.
503 bei einer Löschung: Wiederholen Sie dieselbe Anfrage, bis sie 200 zurückgibt.
Andere 4xx: Korrigieren Sie zuerst die Anfrage, da dieselbe Anfrage auf die gleiche Weise fehlschlägt.

POST /v3/aml/ und die Digital-ID-Wallet-Verifizierung akzeptieren einen Idempotency-Key-Header mit bis zu 255 Zeichen. Das Wiederholen einer Anfrage mit demselben Schlüssel und Payload gibt die gespeicherte Antwort erneut wieder, sodass die Verarbeitung und die Abrechnung nur einmal erfolgen. Derselbe Schlüssel mit einer anderen Payload führt zu einer 409-Antwort, und während die erste Anfrage noch läuft, antworten die Wallet-Endpoints mit 409 und Retry-After. POST /v3/session/ hat keinen Idempotenzschlüssel. Wenn also beim Erstellen eine Zeitüberschreitung auftritt, listen Sie Ihre Sitzungen nach vendor_data auf, bevor Sie eine weitere erstellen.

Leitfäden

Authentifizierung

Model Context Protocol (MCP)

Web-SDKs

Native SDKs

Server-SDKs

Integrationen

API-Fehler in Didit: Statuscodes, Antworten und Behebung

Statuscodes

Fehler-Bodys

Fehler bei API-Schlüsseln

Nicht genügend Credit

Fehlercodes

Zugriff und Abrechnung

Anfragen und Idempotenz

Bank-, Telefon- und Risikoprüfungen

Unternehmensverifizierung (KYB)

Digital-ID-Wallets

Berichte und Fälle

E-Signaturen

Webhooks

Wiederholungsversuche und Idempotenz

Verwandte Themen

​Statuscodes

​Fehler-Bodys

​Fehler bei API-Schlüsseln

​Nicht genügend Credit

​Fehlercodes

​Zugriff und Abrechnung

​Anfragen und Idempotenz

​Bank-, Telefon- und Risikoprüfungen

​Unternehmensverifizierung (KYB)

​Digital-ID-Wallets

​Berichte und Fälle

​E-Signaturen

​Webhooks

​Wiederholungsversuche und Idempotenz

​Verwandte Themen

Statuscodes

Fehler-Bodys

Fehler bei API-Schlüsseln

Nicht genügend Credit

Fehlercodes

Zugriff und Abrechnung

Anfragen und Idempotenz

Bank-, Telefon- und Risikoprüfungen

Unternehmensverifizierung (KYB)

Digital-ID-Wallets

Berichte und Fälle

E-Signaturen

Webhooks

Wiederholungsversuche und Idempotenz

Verwandte Themen