Fehlercodes
Diese Seite ist die einzige Wahrheitsquelle für die Fehlerbehandlung. SDK-spezifische Fehlercodes sind auf der Seite Fehlerbehandlung des jeweiligen SDKs dokumentiert; diese Seite behandelt Fehler auf der Ebene des API-Vertrags.
HTTP-Statuscodes
| Code | Bedeutung | Wo er auftritt |
|---|---|---|
200 OK | Anfrage erfolgreich. | Alle Verträge. |
201 Created | Ressource erstellt (selten; die meisten Erstellungen geben 200 zurück). | API-Vertrag. |
400 Bad Request | Nutzlast ist fehlerhaft oder erforderliche Felder fehlen. Der Body gibt die problematischen Felder an. | Alle Verträge. |
401 Unauthorized | Authentifizierung fehlt, ist abgelaufen oder ungültig. | Alle Verträge. |
403 Forbidden | Die Authentifizierung ist gültig, aber der Mandant ist für die angeforderte Ressource nicht aktiviert (z. B. Aufruf einer Fähigkeit, die nicht in Ihrem APIKEY enthalten ist). | Web & SDK, API. |
404 Not Found | Die Ressource existiert nicht oder gehört nicht zum authentifizierten Mandanten. | Alle Verträge. |
409 Conflict | Die Ressource existiert, befindet sich aber nicht im richtigen Zustand für diesen Vorgang (z. B. Abrufen von Dokumenten aus einem noch laufenden Prozess). | Web & SDK, API. |
410 Gone | Die Ressource existierte, wurde aber gemäß der Aufbewahrungsrichtlinie gelöscht (Dokumentenabruf-Endpunkte), oder der Prozess existiert, endete jedoch im Fehlerzustand — siehe Prozess abrufen. | Dokumentenabruf-Endpunkte; API Prozess abrufen. |
429 Too Many Requests | Sie haben das Rate-Limit überschritten. Wiederholen Sie den Versuch mit exponentiellem Backoff. | Alle Verträge. |
5xx | Plattformfehler. Wiederholen Sie den Versuch mit Backoff; wenn das Problem anhält, wenden Sie sich mit dem Antwort-Body und dem Zeitstempel an den Support. | Alle Verträge. |
Authentifizierungsfehler (401)
| Ursache | Symptom |
|---|---|
| Falscher privater Schlüssel (Assertion mit dem falschen Schlüssel signiert) | 401, Authentication failed (1.2.21) |
aud stimmt nicht mit der Umgebungs-URL überein | 401 |
exp-Claim liegt in der Vergangenheit | 401, Authentication failed |
Nicht unterstützter Algorithmus (verwenden Sie RS256) | 401 |
| Gemischte Sandbox-/Produktions-Anmeldedaten | 401, obwohl Anmeldedaten korrekt aussehen |
Fehlender APIKEY-Header (nur API-Vertrag) | 401 |
Ungültiger x-api-key (nur Magic Link) | 401 |
Siehe Authentifizierung > Häufige Fehler für die vollständige Fehlerbehebungs-Checkliste.
Wiederholungsrichtlinie
| Status | Wiederholen? | Wie |
|---|---|---|
5xx | Ja | Exponentieller Backoff (1s, 2s, 4s, 8s, …). Maximal 5 Versuche. |
429 | Ja | Retry-After-Header beachten, sofern vorhanden; andernfalls exponentieller Backoff. |
4xx (sonstige) | Nein | Die Anfrage ist fehlerhaft. Korrigieren Sie die Eingabe, bevor Sie es erneut versuchen. |
401 | Bedingt | Aktualisieren Sie das Zugriffstoken einmal. Wenn die neue Anfrage ebenfalls 401 zurückgibt, ist das Problem strukturell — nicht erneut versuchen. |
Die IDCloud-Plattform bietet derzeit keinen Idempotenzschlüssel-Mechanismus für Erstellungs-Endpunkte. Seien Sie vorsichtig beim Wiederholen von POST /client/v1/process oder POST /processes/v1 — ein Netzwerkfehler bei einem 5xx kann serverseitig tatsächlich erfolgreich gewesen sein, und ein erneuter Versuch würde einen doppelten Prozess erstellen. Rufen Sie im Zweifelsfall aktuelle Prozesse anhand Ihrer internen Korrelations-ID ab, bevor Sie es erneut versuchen.
Wo SDK-Fehler dokumentiert sind
Die Fehlerkataloge des Web SDK, Android SDK, iOS SDK und Flutter SDK sind auf der dedizierten Seite Fehlerbehandlung jedes SDKs dokumentiert:
- Web SDK > Fehlerbehandlung
- Android SDK > Fehlerbehandlung
- iOS SDK > Fehlerbehandlung
- Flutter SDK > Fehlerbehandlung
Diese umfassen geräteseitige Fehler (Kamerazugriff verweigert, Capture-Timeout, Netzwerk auf dem Gerät nicht erreichbar) — getrennt von den hier dokumentierten API-seitigen Fehlern.