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

# API-Fehler in Didit: Statuscodes, Antworten und Behebung

> Alle Didit-API-Fehler: HTTP-Statuscodes, Antwortformate, Fehlercodes und Wiederholungsversuche. Deckt 401, 403, 409, 429 und 5xx ab.

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](#fehler-bei-api-schlüsseln) sowie [Nicht genügend Credit](#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](https://docs.didit.me/de/integration/rate-limiting.md) | 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](#wiederholungsversuche-und-idempotenz) |
| `502` | Ein Dienst, von dem Didit abhängt, hat einen Fehler zurückgegeben | Lesen Sie `code` aus | Siehe [Wiederholungsversuche](#wiederholungsversuche-und-idempotenz) |
| `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](#wiederholungsversuche-und-idempotenz) |

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

```javascript theme={null}
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](https://docs.didit.me/de/getting-started/api-authentication.md) und [API-Schlüssel](https://docs.didit.me/de/console/api-keys.md) 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](https://docs.didit.me/de/integration/sandbox-testing.md) 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.

## Verwandte Themen

* [Rate-Limits](https://docs.didit.me/de/integration/rate-limiting.md): Limits, Header und der `429`-Body.
* [API-Authentifizierung](https://docs.didit.me/de/getting-started/api-authentication.md): So übermitteln Sie Ihren Schlüssel.
* [Sandbox-Tests](https://docs.didit.me/de/integration/sandbox-testing.md): Ergebnisse ohne echte Daten oder Abrechnung reproduzieren.
* [Webhooks](https://docs.didit.me/de/integration/webhooks.md): Zustellung, Wiederholungsversuche und Reihenfolge.


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