Fehlerbehandlung
Dieser Leitfaden beschreibt das Fehlerantwortformat der OfoxAI API, häufige Fehlerszenarien und empfohlene Behandlungsstrategien.
Fehlerantwortformat
Alle Fehlerantworten folgen einem einheitlichen JSON-Format:
{
"error": {
"code": "invalid_api_key",
"message": "Der angegebene API Key ist ungültig. Bitte überprüfen und erneut versuchen.",
"type": "authentication_error"
}
}HTTP-Statuscodes
| Statuscode | Typ | Beschreibung | Wiederholung? |
|---|---|---|---|
400 | invalid_request_error | Fehlerhafte Anfrageparameter | Nein — Parameter korrigieren |
401 | authentication_error | API Key ungültig oder fehlend | Nein — API Key prüfen |
403 | permission_error | Unzureichende Berechtigungen | Nein — Kontoberechtigungen prüfen |
404 | not_found_error | Modell oder Ressource nicht gefunden | Nein — Modell-ID prüfen |
429 | rate_limit_error | Ratenlimit erreicht | Ja — nach Wartezeit wiederholen |
500 | internal_error | Interner Serverfehler | Ja — später wiederholen |
502 | upstream_error | Fehler beim Upstream-Modellanbieter | Ja — Modell wechseln oder wiederholen |
503 | service_unavailable | Dienst vorübergehend nicht verfügbar | Ja — später wiederholen |
Häufige Fehler und Lösungen
401 — Ungültiger API Key
{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}Lösung:
- Prüfen Sie, ob der API Key korrekt kopiert wurde (mit
sk--Präfix) - Stellen Sie sicher, dass der Key nicht abgelaufen oder deaktiviert ist
- Überprüfen Sie, ob die Umgebungsvariable korrekt geladen wird
429 — Ratenlimit
{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}Lösung:
- Prüfen Sie den Response-Header
x-ratelimit-reset-requests - Implementieren Sie exponentielles Backoff
- Kontaktieren Sie bei Bedarf den Support für eine höhere Quote
502 — Upstream-Fehler
{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}Lösung:
- Verwenden Sie Failover für den automatischen Wechsel auf ein Ersatzmodell
- Später erneut versuchen
- Statusseite des Modellanbieters prüfen
Wiederholungsstrategie
Empfohlen wird eine Strategie mit exponentiellem Backoff:
retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
client = OpenAI(
base_url="https://api.ofox.ai/v1",
api_key="<Ihr OFOXAI_API_KEY>"
)
def chat_with_retry(max_retries=5, **kwargs):
"""Wiederholungs-Wrapper mit exponentiellem Backoff"""
for attempt in range(max_retries):
try:
return client.chat.completions.create(**kwargs)
except RateLimitError:
# 429: Warten und wiederholen
wait = (2 ** attempt) + random.uniform(0, 1)
print(f"Ratenlimit erreicht, warte {wait:.1f}s...")
time.sleep(wait)
except APIConnectionError:
# Netzwerkfehler: Kurz warten und wiederholen
wait = 2 ** attempt
print(f"Verbindungsfehler, warte {wait}s...")
time.sleep(wait)
except APIError as e:
if e.status_code and e.status_code >= 500:
# 5xx: Serverfehler, wiederholen
wait = 2 ** attempt
time.sleep(wait)
else:
# 4xx: Clientfehler, nicht wiederholen
raise
raise Exception(f"Nach {max_retries} Versuchen fehlgeschlagen")
# Verwendung
response = chat_with_retry(
model="openai/gpt-4o",
messages=[{"role": "user", "content": "Hallo"}]
)Timeout-Einstellungen
Es empfiehlt sich, für API-Aufrufe einen angemessenen Timeout zu konfigurieren:
# Python OpenAI SDK
client = OpenAI(
base_url="https://api.ofox.ai/v1",
api_key="<Ihr OFOXAI_API_KEY>",
timeout=60.0, # 60 Sekunden Timeout
max_retries=3 # SDK-integrierte Wiederholung
)// TypeScript OpenAI SDK
const client = new OpenAI({
baseURL: 'https://api.ofox.ai/v1',
apiKey: '<Ihr OFOXAI_API_KEY>',
timeout: 60000, // 60 Sekunden Timeout
maxRetries: 3 // SDK-integrierte Wiederholung
})Für Streaming-Anfragen empfiehlt sich ein längerer Timeout (120–300 Sekunden), da das Modell möglicherweise mehr Zeit für die vollständige Generierung benötigt.
Best Practices
- Wiederholbare und nicht wiederholbare Fehler unterscheiden — 4xx erfordern meist eine Korrektur der Anfrage, 5xx können wiederholt werden
- Exponentielles Backoff verwenden — Häufige Wiederholungen bei Drosselung vermeiden
- Maximale Wiederholungszahl festlegen — Endlosschleifen verhindern
- Fehler protokollieren — Erleichtert die Problemdiagnose
- Failover konfigurieren — Nutzen Sie den OfoxAI-Parameter
provider.fallbackfür automatischen Modellwechsel - Fehlerrate überwachen — Beobachten Sie Fehlertrends in der Konsole
Last updated on