Skip to Content
LeitfädenFehlerbehandlung und Wiederholungen

Fehlerbehandlung

Dieser Leitfaden beschreibt das Fehlerantwortformat der OfoxAI API, häufige Fehlerszenarien und empfohlene Behandlungsstrategien. Anfragen, die von einem Ausgabenlimit oder einer Zugriffsregel gestoppt werden (402 / 403), gelingen auch bei Wiederholung nicht; sie erscheinen in der Konsole unter Aktivität (Activity) im Filter Blockiert (Blocked). Unter API Keys zeigt das Key-Menü → Wirksame Regeln prüfen (Check effective rules), ob ein Modell blockiert würde, ohne Guthaben zu verbrauchen.

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

StatuscodeTypBeschreibungWiederholung?
400invalid_request_errorFehlerhafte AnfrageparameterNein — Parameter korrigieren
401authentication_errorAPI Key ungültig oder fehlendNein — API Key prüfen
402insufficient_creditsGuthaben nicht ausreichendNein — Guthaben aufladen, dann wiederholen
402spending_limit_exceededAusgabenlimit erreicht (Team, Mitglied oder Key)Nein — Limit erhöhen oder Zurücksetzen des Tages-/Monatszeitraums abwarten; Aufladen hilft nicht
403ip_not_allowedAufrufende IP steht nicht in der IP-Allowlist von Team oder KeyNein — IP unter Einstellungen → Limits und Zugriff (Settings → Limits & access) oder in der IP-Allowlist (IP Whitelist) des Keys hinzufügen
403model_not_allowedTeam oder Key erlaubt dieses Modell nichtNein — anderes Modell nutzen oder erlaubte Modelle von Team / Key anpassen
403permission_errorSonstige fehlende BerechtigungenNein — Kontoberechtigungen prüfen
404not_found_errorModell oder Ressource nicht gefundenNein — Modell-ID prüfen
429rate_limit_errorRatenlimit erreichtJa — nach Wartezeit wiederholen
500internal_errorInterner ServerfehlerJa — später wiederholen
502upstream_errorFehler beim Upstream-ModellanbieterJa — Modell wechseln oder wiederholen
503service_unavailableDienst vorübergehend nicht verfügbarJa — später wiederholen
503spending_limit_check_unavailableAusgabenlimit kann vorübergehend nicht geprüft werdenJa — 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.io/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-6.1-sol", 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.io/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.io/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

  1. Wiederholbare und nicht wiederholbare Fehler unterscheiden — 4xx erfordern meist eine Korrektur der Anfrage, 5xx können wiederholt werden
  2. Exponentielles Backoff verwenden — Häufige Wiederholungen bei Drosselung vermeiden
  3. Maximale Wiederholungszahl festlegen — Endlosschleifen verhindern
  4. Fehler protokollieren — Erleichtert die Problemdiagnose
  5. Failover konfigurieren — Nutzen Sie den OfoxAI-Parameter provider.fallback für automatischen Modellwechsel
  6. Fehlerrate überwachen — Beobachten Sie Fehlertrends in der Konsole
Zuletzt aktualisiert am