Anleitungen
Fehler und Wiederherstellung
Nutzen Sie stabile Fehlercodes, strukturierte Details und Anfragekennungen, um Korrekturen und Wiederholungen zu bestimmen.
Einheitliche Fehlerhülle
Fehler enthalten ein error-Objekt mit type, code, message, request_id und optional details. Entscheiden Sie anhand HTTP-Status und stabilem code; die Meldung dient der Diagnose. Jede Antwort enthält auch X-Request-Id. Bewahren Sie diese Kennung für Problemmeldungen auf, ohne Schlüssel oder sensible Payloads zu protokollieren.
{
"error": {
"type": "validation_error",
"code": "validation_failed",
"message": "The supplied field is not available.",
"details": { "unknown": ["nname"], "nearest": { "nname": ["name"] } },
"request_id": "4d85a25f-d510-41f5-b228-32a875670fd0"
}
}Passende Reaktion wählen
Korrigieren Sie ungültige Eingaben und Zugriffsprobleme vor Wiederholungen. Ein 404 gilt auch für einen Datensatz aus einem anderen Arbeitsbereich oder außerhalb der Sichtbarkeit des Eigentümers.
| Status | Codes | Reaktion |
|---|---|---|
| 400 | invalid_request | JSON, Parameter, Filter oder Cursor-Einstellungen korrigieren. |
| 401 | invalid_api_key, expired_api_key, key_assurance_stale | Geheimnis, Ablauf und MFA prüfen; bei Bedarf Schlüssel ersetzen. |
| 403 | ip_not_allowed, permission_denied, plan_upgrade_required, insufficient_scope, feature_unavailable, forbidden | Server-IP, Mitgliedschaft, Rolle, Tarif, Umfang und Verfügbarkeit prüfen. |
| 404 | not_found, unknown_resource, route_not_found | Pfad, Kennungen und Sichtbarkeit des Eigentümers prüfen. |
| 405 | method_not_allowed | Unterstützte Methode aus Allow verwenden; manche Ressourcen sind nur lesbar. |
| 409 | conflict, idempotency_key_in_use | Konflikt lösen oder vor gleicher idempotenter Anfrage warten. |
| 413 | payload_too_large | Anfragekörper auf höchstens 1 MiB reduzieren. |
| 422 | validation_failed, idempotency_key_reused | Felder/Typen korrigieren oder neuen Schlüssel für andere Operation verwenden. |
| 429 | rate_limited, quota_exceeded | Retry-After beachten; Limiten und Kontingentreset prüfen. |
| 500 / 503 | internal_error, service_unavailable | Mit begrenztem Backoff wiederholen; Idempotenzschlüssel beibehalten. |
Details statt Vermutungen nutzen
Validierungsdetails können unknown, nearest und alternatives mit korrigierbaren Feldern oder Optionen enthalten. Paginierungsfehler können max_page liefern, Kontingentfehler resets_at, Datenbankvalidierung sqlstate und einen relevanten hint. Beschreiben Sie die Ressource erneut, wenn sich das Schema geändert hat.
Wiederholungen begrenzen
Verwenden Sie bei temporären Fehlern eine begrenzte Anzahl Versuche mit exponentiellem Backoff und Zufallsstreuung. Beachten Sie vorhandenes Retry-After. Wiederholen Sie 400, 401, 403 oder Validierungsfehler nicht automatisch. Bewahren Sie bei Schreibwiederholungen die exakte Anfrage und den Idempotenzschlüssel und prüfen Sie unklare Ergebnisse vor einer neuen Änderung.