Fehlerbehandlung
Die API verwendet konventionelle HTTP-Antwortcodes, um den Erfolg oder Misserfolg von Anfragen anzuzeigen. Diese Seite dokumentiert Fehlerformate und Behandlungsstrategien.
Fehlerantwortformat
Alle Fehlerantworten folgen einer einheitlichen JSON-Struktur:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Feld | Beschreibung |
|---|---|
| error | Maschinenlesbarer Fehlercode |
| message | Für Menschen lesbare Fehlerbeschreibung |
| timestamp | Zeitpunkt des Fehlers |
| path | Pfad des angeforderten Endpunkts |
| details | Zusätzliche Details für Validierungsfehler (optional) |
HTTP-Statuscodes
| Code | Beschreibung |
|---|---|
| 400 | Ungültige Anfrageparameter oder fehlerhafter Anfragekörper |
| 401 | Fehlender oder ungültiger API-Schlüssel |
| 403 | API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen für diesen Endpunkt |
| 404 | Die angeforderte Ressource existiert nicht |
| 429 | Rate-Limit überschritten - bitte nach der angegebenen Zeit erneut versuchen |
| 500 | Interner Serverfehler - bitte kontaktieren Sie den Support, falls das Problem weiterhin besteht |
| 503 | Dienst vorübergehend nicht verfügbar - versuchen Sie es später erneut |
Wiederholungsstrategie
Implementieren Sie für vorübergehende Fehler eine Wiederholungsstrategie mit exponentieller Rückfallverzögerung (Exponential Backoff):
- Warten Sie bei 429-Fehlern, bis die in der X-RateLimit-Reset-Kopfzeile angegebene Zeit verstrichen ist, bevor Sie es erneut versuchen.
- Verwenden Sie für 5xx-Fehler eine exponentielle Rückfallverzögerung (1s, 2s, 4s, 8s...) mit Jitter (zufällige Schwankung).
- Legen Sie eine maximale Anzahl von Wiederholungsversuchen fest (z. B. 3-5 Versuche), um Endlosschleifen zu vermeiden.
Ratenbegrenzung
Wenn Sie die Ratenbegrenzung überschreiten, gibt die API einen Statuscode 429 mit Details zurück, wann Sie es erneut versuchen können:
Verwenden Sie das Feld retryAfter oder den Header X-RateLimit-Reset, um zu bestimmen, wann Sie Ihre Anfrage erneut stellen können.
Validierungsfehler
Bei 400-Fehlern enthält die Antwort ein Array mit Details zu spezifischen Fehlern auf Feldebene:
Best Practices für die Fehlerbehandlung
- Überprüfen Sie immer den HTTP-Statuscode, bevor Sie den Antwortkörper analysieren
- Implementieren Sie exponentielles Backoff für 429- und 5xx-Fehler
- Protokollieren Sie Fehler mit Zeitstempel und Pfad zur Fehlerbehebung
- Spezifische Fehlercodes unterschiedlich behandeln (z. B. 401 löst erneute Authentifizierung aus)