Fehler-Antwortformat
Alle Fehler geben ein konsistentes JSON-Format mit optionalen Agent-First-Hinweisen zurück:message, type, code, param) sind immer vorhanden. Die Hinweisfelder (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) sind optionale Erweiterungen zur Selbstkorrektur von AI-Agenten. Siehe den Agent-First API-Leitfaden für Details.
OpenAI-kompatible Endpunkte verwenden LemonData’s stabile Gateway-Fehlertypen. Anthropic-kompatible und Gemini-kompatible Endpunkte verwenden ihre eigenen nativen Fehlerfamilien und Antwortformate.
HTTP-Statuscodes
| Code | Beschreibung |
|---|---|
| 400 | Bad Request - Ungültige Parameter |
| 401 | Unauthorized - Ungültiger oder fehlender API-Schlüssel |
| 402 | Payment Required - Unzureichendes Guthaben |
| 403 | Forbidden - Zugriff verweigert oder Modell nicht erlaubt |
| 404 | Not Found - Modell oder Ressource nicht gefunden |
| 413 | Payload Too Large - Eingabe- oder Dateigröße überschritten |
| 429 | Too Many Requests - Ratenlimit überschritten |
| 500 | Internal Server Error |
| 502 | Bad Gateway - Fehler des Upstream-Providers |
| 503 | Service Unavailable - Dienst vorübergehend nicht verfügbar |
| 504 | Gateway Timeout - Anfrage hat zu lange gedauert |
Fehlertypen
Authentifizierungsfehler (401)
| Typ | Code | Beschreibung |
|---|---|---|
invalid_api_key | invalid_api_key | API-Schlüssel fehlt oder ist ungültig |
expired_api_key | expired_api_key | API-Schlüssel wurde widerrufen |
Zahlungsfehler (402)
| Typ | Code | Beschreibung |
|---|---|---|
insufficient_balance | insufficient_balance | Kontostand ist zu niedrig (OpenAI-kompatible Endpunkte) |
insufficient_balance_error | insufficient_balance | Kontostand ist zu niedrig (Anthropic-kompatible Endpunkte) |
quota_exceeded | quota_exceeded | Nutzungslimit des API-Schlüssels erreicht |
Zugriffsfehler (403)
| Typ | Code | Beschreibung |
|---|---|---|
access_denied | access_denied | Zugriff auf die Ressource verweigert |
access_denied | model_not_allowed | Modell für diesen API-Schlüssel nicht erlaubt |
Validierungsfehler (400)
| Typ | Beschreibung |
|---|---|
invalid_request_error | Anfrageparameter sind ungültig |
context_length_exceeded | Eingabe ist zu lang für das Modell |
model_not_found | Angefordertes Modell ist im aktuellen öffentlichen Vertrag nicht verfügbar |
model_not_found zurück.
Rate-Limit-Fehler (429)
Wenn Sie die Ratenbegrenzungen überschreiten:Retry-After-Header und das Feld retry_after geben beide die exakte Anzahl an Sekunden an, die vor einem erneuten Versuch gewartet werden soll.
Payload zu groß (413)
Wenn Eingabe oder Dateigröße die Grenzwerte überschreitet:- Bilddatei zu groß (max 20MB)
- Audiodatei zu groß (max 25MB)
- Eingabetext überschreitet die Kontextlänge des Modells
Upstream-Fehler (502, 503)
| Typ | Beschreibung |
|---|---|
upstream_error | Provider hat einen Fehler zurückgegeben |
all_channels_failed | Keine verfügbaren Provider |
timeout_error | Anfrage ist zeitlich überschritten |
Fehlerbehandlung in Python
Fehlerbehandlung in JavaScript
Beste Vorgehensweisen
Exponential Backoff implementieren
Exponential Backoff implementieren
Wenn Sie rate-limited sind, warten Sie bei erneuten Versuchen schrittweise länger:
Timeouts setzen
Timeouts setzen
Setzen Sie immer vernünftige Timeouts, um hängende Anfragen zu vermeiden:
Fehler zum Debugging protokollieren
Fehler zum Debugging protokollieren
Protokollieren Sie die vollständige Fehlerantwort inklusive Request-ID für den Support:
Modellspezifische Fehler behandeln
Modellspezifische Fehler behandeln
Einige Modelle haben spezifische Anforderungen (z. B. maximale Tokens, Bildformate).
Validieren Sie Eingaben, bevor Sie Anfragen stellen.