Häufige LiteLLM-Fehler: Timeouts, Budgetwarnungen und Provider-Ausfälle

Häufige LiteLLM-Fehler: Timeouts, Budgetwarnungen und Provider-Ausfälle

Die meisten häufigen LiteLLM-Fehler sehen zunächst wie ein Provider-Problem aus: Eine Anfrage läuft in ein Timeout, eine Budgetwarnung trifft nie ein oder ein fehlerfreies Modell gibt plötzlich einen 404- oder 503-Fehler zurück. Die schnellste Lösung besteht darin, die fehlerhafte Steuerungsebene zu identifizieren, bevor Sie Wiederholungsversuche ändern oder Modelle austauschen.

Nutzen Sie diesen Leitfaden, um Client-Deadlines, LiteLLM-Gateway-Richtlinien, Modellkonfiguration, Provider-Kapazität und Ausgaben-Durchsetzung voneinander zu trennen. Er enthält einen kleinen Incident-Workflow, den Sie für Timeouts, Budgetkontrollen und Provider-Ausfälle wiederholen können.

Kurzantwort: Bewahren Sie eine fehlgeschlagene Anfrage auf, klassifizieren Sie den Fehler, reproduzieren Sie ihn mit einem minimalen Aufruf und ändern Sie jeweils nur eine Steuerung. Beginnen Sie mit LiteLLMs normalisiertem Ausnahmetyp, den Anfrage-Metadaten und der Aufruf-ID – nicht nur mit dem HTTP-Status.

LiteLLM ordnet viele Provider-Fehler OpenAI-kompatiblen Ausnahmetypen zu und stellt den HTTP-Status, die Meldung und den verursachenden Provider in der Ausnahme bereit. Dadurch lassen sich häufige LiteLLM-Fehler leichter beheben, wenn Sie den ursprünglichen Fehlerkontext intakt halten, statt ihn durch einen generischen 500-Fehler zu ersetzen. Die aktuelle Zuordnung finden Sie in der Referenz zur LiteLLM-Ausnahmezuordnung.

Die Matrix häufiger LiteLLM-Fehler

Diese Tabelle ist das wichtigste Element dieses Leitfadens zu häufigen LiteLLM-Fehlern: Sie verwandelt einen vagen Gateway-Fehler in die nächste konkrete Beobachtung.

Ein fünfminütiger Triage-Ablauf für häufige LiteLLM-Fehler

Bevor Sie config.yaml bearbeiten, speichern Sie einen repräsentativen Fehler. Schwärzen Sie bei Bedarf Geheimnisse und Prompt-Inhalte, behalten Sie jedoch die operativen Felder bei.

1. Die Anfrageidentität erfassen. Notieren Sie Zeitstempel, Umgebung, Route, angefordertes model, HTTP-Status, LiteLLM-Ausnahmetyp, Fehlermeldung, Provider-Name und Nummer des Client-Versuchs.
2. Die Gateway-Identität erfassen. Speichern Sie x-litellm-call-id, falls vorhanden. LiteLLM dokumentiert diesen Header als beste Referenz, um eine Anfrage durch Protokollierungssysteme zu verfolgen. Notieren Sie außerdem x-litellm-model-id, x-litellm-model-api-base und Versions-Header, falls Ihre Antwort diese bereitstellt. Die LiteLLM-Protokollierungsdokumentation führt die aktuellen Header auf.
3. Den Fehler klassifizieren. Handelt es sich um eine ungültige Anfrage, ein Authentifizierungs-/Berechtigungsproblem, ein Budget-/Ratenlimit, ein Timeout oder einen Upstream-Dienstausfall? Legen Sie nicht alle 4xx-Fehler in denselben Bucket für Wiederholungsversuche.
4. Eine minimale Reproduktion außerhalb der Produktion durchführen. Verwenden Sie denselben virtuellen Schlüssel und denselben öffentlichen model_name, den die Anwendung nutzt. Entfernen Sie anwendungsspezifische Parallelität und Tool-Aufrufe, bevor Sie eine grundlegende Anfrage testen.
5. Nur eine Ebene ändern. Eine Modellnamenkorrektur, eine Timeout-Änderung und eine Fallback-Änderung im selben Deployment machen das Endergebnis unmöglich erklärbar.

Hier ist ein allgemeiner minimaler Testaufruf für einen OpenAI-kompatiblen LiteLLM-Proxy:

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

Der entscheidende Punkt ist nicht, dass support-chat ein universeller Modellname ist. Entscheidend ist, dass der Test den in Ihrem Gateway konfigurierten öffentlichen Namen verwendet und anschließend die Antwort-Header und den -Body zum Vergleich mit der fehlgeschlagenen Anwendungsanfrage aufbewahrt.

Timeout-Fehler: Finden Sie die Frist, die tatsächlich ausgelöst wurde

Timeouts gehören zu den irreführendsten häufigen LiteLLM-Fehlern, da eine Anfrage auf mehr als einer Ebene ablaufen kann:

• Der Aufrufer kann zuerst abbrechen.
• Die LiteLLM-Bereitstellung oder der Router kann eine kürzere Frist anwenden.
• Das request_timeout des Proxys kann einen lang laufenden Upstream-Aufruf stoppen.
• Der Provider, Load Balancer oder Netzwerkpfad kann die Anfrage schließen.
• Eine gestreamte Antwort kann erfolgreich beginnen und dann zwischen Chunks hängen bleiben.

Die Ausnahmezuordnung von LiteLLM dokumentiert Timeout-Fehler als openai.APITimeoutError. Für native und Pass-through-Routen beschreibt die aktuelle Timeout-Dokumentation eine Vorrangreihenfolge zwischen Anfrage-, Bereitstellungs-, Router- und Proxy-Einstellungen. Prüfen Sie vor einer Konfigurationsänderung die Version der Dokumentation, die zu Ihrer Bereitstellung passt.

Beginnen Sie mit einem Fristbudget, nicht mit einer größeren Zahl

Wählen Sie die Gesamtlatenz, die Ihr Nutzerfluss tolerieren kann, und teilen Sie sie anschließend rückwärts zu. Eine interaktive Erfahrung könnte beispielsweise Zeit für Warteschlangen, einen Wiederholungsversuch und das Rendern der Antwort reservieren, statt den Upstream-Aufruf die gesamte für den Nutzer sichtbare Frist verbrauchen zu lassen.

# Illustrativer Ausgangspunkt — passen Sie ihn an Ihre Workload und LiteLLM-Version an.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

Das Beispiel ist absichtlich konservativ: Es gibt dem Proxy einen begrenzten Fehlermodus, statt Verbindungen hängen zu lassen. Die Produktionsleitlinien von LiteLLM empfehlen, ein Anfrage-Timeout festzulegen und strukturiertes Produktions-Logging zu verwenden.

Wenn ein Timeout auftritt, beantworten Sie diese Fragen der Reihe nach:

Lassen Sie einen automatisierten Timeout-Wiederholungsversuch nicht unbegrenzt laufen. Ein Retry ist nur sinnvoll, wenn die Arbeit sicher wiederholt werden kann und ein alternativer Versuch noch innerhalb der Frist des Aufrufers abgeschlossen werden kann. Wenn eine Anfrage Tools auslöst, Daten schreibt oder einen für Nutzer sichtbaren Stream beginnt, definieren Sie zuerst Idempotenz- und Neustartsemantik.

Bei durch 429 verursachten Warteschlangen- oder Kapazitätsproblemen, die sich als hohe Latenz zeigen, ergänzen Sie diesen Abschnitt mit Flatkeys Leitfaden zu RPM, TPM und Retries. Ein Timeout kann das Symptom einer überlasteten Zulassungssteuerung sein, nicht einer Einstellung für die Anfragedauer.

Budgetwarnungen: Benachrichtigung von Durchsetzung trennen

Budgetverhalten verursacht einen unverhältnismäßig großen Anteil der häufigen LiteLLM-Fehler, weil Teams häufig drei verschiedene Kontrollen unter dem Begriff „Warnung“ zusammenfassen. Sie sind nicht austauschbar.

Die erste Budgetprüfung: Gibt es eine Datenbank?

Die aktuelle Budgetdokumentation von LiteLLM ist eindeutig: Die Proxy-Budgets werden anhand von Ausgaben durchgesetzt, die aus der Datenbank gelesen werden. Bei einer Bereitstellung ohne Datenbank fungiert ein konfiguriertes globales max_budget nicht als zuverlässige Ausgabenobergrenze; auch das Budgetverhalten für virtuelle Schlüssel, Teams und Nutzer hängt von der Datenbank ab.

Daraus ergibt sich ein häufiges Fehlermuster: Ein Team setzt max_budget, sieht eine Startwarnung oder einen Konfigurationswert und nimmt an, dass der Produktionsverkehr am Schwellenwert stoppt. Ohne die erforderliche Einrichtung zur Ausgabenverfolgung ist dies keine verlässliche Kontrolle.

# Illustrative policy only. Validate with a non-production key before rollout.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

Betrachten Sie fail_closed_budget_enforcement als Zuverlässigkeitsentscheidung, nicht als Copy-paste-Lösung. Die aktuelle LiteLLM-Dokumentation erläutert, dass eine strengere Budgetprüfung Anfragen ablehnen kann, wenn Ausgaben nicht verifiziert werden können; testen Sie vor einer breiten Aktivierung das Ausfallverhalten von Datenbank und Redis für Ihre Bereitstellung.

Testen Sie den Budgetpfad, nicht nur das Dashboard

Verwenden Sie einen temporären Schlüssel oder ein Team in einer Nicht-Produktivumgebung und überprüfen Sie diese Abfolge:

1. Bestätigen Sie, dass der Proxy den Ausgabenspeicher lesen und beschreiben kann.
2. Erstellen Sie ein absichtlich kleines festes Budget im richtigen Geltungsbereich: Schlüssel, Team, Benutzer, Projekt oder Endbenutzer.
3. Senden Sie eine minimale Anfrage über den Proxy.
4. Senden Sie eine zweite Anfrage, die den Schwellenwert zwingend überschreiten muss.
5. Prüfen Sie die zurückgegebene Ausnahme, den Ausgabendatensatz, das Rücksetzfenster und den Warnkanal unabhängig voneinander.
6. Bestätigen Sie, dass die Anwendung eine Budgetblockierung verarbeitet, ohne sie erneut zu versuchen, als handele es sich um eine vorübergehende Providerüberlastung.

LiteLLM dokumentiert außerdem Budgetfenster und Budgetkontrollen pro Modell. Seien Sie beim Rücksetzzeitplan präzise: Ein tägliches Sicherheitslimit und eine monatliche Obergrenze mindern unterschiedliche Risiken.

Azure-Budgetwarnungen und AWS-Budgetwarnungen sind Absicherungen, kein Ersatz

Die sekundären Keywords Azure budget alerts und AWS budget alerts sind wichtig, weil Abrechnungswarnungen von Cloud-Providern eine andere Grenze abdecken. Sie können vor Ausgaben auf Providerkonto- oder Abonnementebene warnen, einschließlich Datenverkehr, der LiteLLM umgeht. Sie ersetzen keine Entscheidung auf Gateway-Ebene darüber, ob diese Anfrage, dieser Schlüssel, dieser Mandant oder dieses Modell jetzt zugelassen werden soll.

Verwenden Sie gegebenenfalls beide Ebenen:

• Die LiteLLM-Budgetrichtlinie schützt die Route und den Mandanten, die das Gateway identifizieren kann.
• Azure-Budgetwarnungen oder AWS-Budgetwarnungen überwachen die Ausgaben des vorgelagerten Cloud-Kontos.
• Ein Gateway-Nutzungsledger gleicht beide ab und macht Datenverkehr sichtbar, der den vorgesehenen Pfad umgangen hat.

Für OpenAI-Ausgaben kann LiteLLMs Prüfung der Ausgabenerfassungsrate erfasste Ausgaben mit der OpenAI Organization Costs API vergleichen. Sie hat derzeit providerspezifische Voraussetzungen. Lesen Sie daher die versionierte Dokumentation, bevor Sie sie als universelle Abgleichsfunktion für mehrere Provider betrachten.

Wenn der betriebliche Bedarf über eine einzelne LiteLLM-Bereitstellung hinausgeht, finden Sie im Leitfaden zur Bewertung einheitlicher KI-Abrechnungs-Dashboards die Fragen, die Sie zu Schlüsseln, Budgets, Zuweisungen, Warnungen und Abgleich stellen sollten.

Provider-Ausfälle: Überprüfen Sie den öffentlichen Modellnamen und die vorgelagerte Bereitstellung getrennt

Provider-Ausfälle sind die sichtbarsten LiteLLM Common Errors, häufig handelt es sich jedoch um Fehler in der Gateway-Konfiguration. Ein Client ruft typischerweise den öffentlichen model_name auf, den Sie bereitstellen. LiteLLM löst diesen Namen dann in ein Provider-Modell, eine Bereitstellung, einen Endpunkt, Anmeldedaten und providerspezifische Parameter auf.

model_list:
  - model_name: support-chat       # The name the client requests
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

Der model_name und litellm_params.model sind bewusst unterschiedliche Konzepte. Wenn ein Client einen Fehler für ein ungültiges Modell erhält, vergleichen Sie zuerst den exakt angeforderten Namen mit model_name. LiteLLMs Dokumentation zur Modellverwaltung unterscheidet zwischen dem öffentlichen Modellnamen und dem Provider-Modell und bietet einen Workflow für Verbindungstests konfigurierter Modelle.

Entscheidungstabelle für Provider-Ausfälle

Der Ausnahmetyp sollte die nächste Maßnahme bestimmen. Die Ausnahmereferenz von LiteLLM ordnet Zustände mit 401, 402, 403, 404, 408, 429, 500 und 503 normalisierten Klassen zu; sie stellt zudem anbieterspezifische Felder für weitergehende Untersuchungen bereit.

Wiederholungen, Fallbacks und Cooldowns: Wiederherstellung ohne Verschleierung des Vorfalls

Wiederholungen und Fallbacks können sichtbare Fehler reduzieren, aber sie können auch einen Konfigurationsfehler in Latenz, Kosten oder doppelte Arbeit verwandeln. Ein guter Umgang mit häufigen LiteLLM-Fehlern verwendet für eine ungültige Konfiguration eine andere Richtlinie als für eine kurze Unterbrechung beim Anbieter.

LiteLLM dokumentiert eine nützliche Aufteilung:

• Wiederholungen versuchen, innerhalb der aktuellen Modellgruppe eine Wiederherstellung zu erreichen.
• Fallbacks wechseln nach den konfigurierten Wiederholungen zu einer anderen Modellgruppe.
• Cooldowns isolieren ein fehlerhaftes Deployment, während funktionsfähige Alternativen verfügbar bleiben.

Hier ist eine kleine beispielhafte Konfiguration auf Grundlage von LiteLLMs Leitfaden für Provider-Failover:

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

Validieren Sie dies ausschließlich mit einem absichtlich ausgelösten Anbieterfehler außerhalb der Produktion. Die Dokumentation von LiteLLM warnt davor, dass ältere Mock-Fallback-Flags keine Proxy-Anfragen testen; ein echter, kontrollierter Fehler ist der geeignete Validierungsweg für den Proxy.

Halten Sie Bedingungen mit 404, Authentifizierung, Berechtigung, Schema und Inhaltsrichtlinien aus einer allgemeinen Wiederholungsschleife heraus, sofern Sie nicht ausdrücklich eine separate Reaktion dafür entworfen haben. Die Routing-Dokumentation von LiteLLM unterstützt fehlerspezifische Wiederholungsrichtlinien, einschließlich null Wiederholungen für NotFoundError; dadurch wird aus einem ungültigen Modellnamen kein langsamer Vorfall.

Validieren Sie vor der Aktivierung eines anbieterübergreifenden Fallbacks den Produktvertrag:

• Verhalten des Kontextfensters und Semantik von Tool-Aufrufen
• Unterstützung für strukturierte Ausgaben und Antwortformate
• Anforderungen an Datenresidenz, Aufbewahrung und Kundenrichtlinien
• Erwartungen an Sicherheitsverhalten und Inhaltsrichtlinien
• Grenzen für Latenz und Kosten
• Idempotenz nachgelagerter Seiteneffekte

Fallbacks sollten nach der Anfrage beobachtbar sein und nicht stillschweigend erfolgen. LiteLLM dokumentiert Felder wie versuchte Fallbacks und die ursprüngliche Modellgruppe in Metadaten von Ausgabenprotokollen. Überwachen Sie die Fallback-Rate, die endgültige Erfolgsrate, die durch Wiederholung/Fallback hinzugefügte Latenz und die Kosten der Route, die die Anfrage tatsächlich bedient hat.

Ein umfassenderes Routing-Design finden Sie im Playbook für Fallback-Routing von Flatkey. Dieselbe Regel gilt: Leiten Sie nur weiter, wenn die Alternative weiterhin den Vertrag des Workflows erfüllt.

Eine vorfallsbereite Checkliste für LiteLLM-Probleme

Führen Sie diese Checkliste aus, bevor Sie einen Vorfall abschließen oder einen der häufigen LiteLLM-Fehler als behoben erklären.

Wann die Routing-Oberfläche vereinfacht werden sollte

Einige Teams möchten LiteLLM, weil es Modellkonfiguration, Nutzung und Zuverlässigkeitsrichtlinien zentralisiert. Andere möchten weniger Gateway-Infrastruktur betreiben. Die richtige Antwort hängt davon ab, wer für Routing-Richtlinien, Anbieterzugangsdaten, Budgetdurchsetzung und den Vorfallsreaktionszyklus verantwortlich ist.

Flatkey ist nützlich, wenn eine Anwendung eine OpenAI-kompatible Integrationsoberfläche über unterstützte Modellrouten hinweg benötigt und Routing, Nutzungsprüfung und Abrechnung enger zusammenhalten möchte. Es beseitigt nicht die Notwendigkeit, Timeouts, Budgetblockierungen oder Provider-Fehler zu klassifizieren; es reduziert die Anzahl providerspezifischer Client-Integrationen, die Ihre Anwendung pflegen muss. Beginnen Sie mit einem API-Schlüssel für mehrere KI-Modelle oder dem Flatkey API-Schnellstart, wenn Sie dieses Betriebsmodell evaluieren möchten.

Eine vollständige Anleitung zur Einrichtung und ein Konfigurationsbeispiel finden Sie in unserem LiteLLM-Proxy-Leitfaden.

FAQ

Können alle häufigen LiteLLM-Fehler sicher erneut versucht werden?

Nein. Authentifizierungs-, Berechtigungs-, ungültige Modell-, nicht unterstützte Parameter-, Budget- und die meisten Abrechnungsfehler erfordern eine Korrektur der Konfiguration oder des Kontos. Wiederholen Sie nur eindeutig vorübergehende Zustände, mit einem kleinen Versuchs- und Zeitbudget und nur dann, wenn der Vorgang sicher wiederholt werden kann.

Warum stoppt max_budget die Ausgaben in meinem LiteLLM-Proxy nicht?

Überprüfen Sie zunächst, ob der Proxy über das datenbankgestützte Ausgaben-Tracking verfügt, das für die Budgetdurchsetzung erforderlich ist. Bestätigen Sie dann, dass der Datenverkehr LiteLLM erreicht, statt einen Provider direkt aufzurufen, und dass der konfigurierte Schlüssel, das Team, der Benutzer oder das Projekt tatsächlich den Scope bildet, der die Anfrage stellt. Die Budgetdokumentation von LiteLLM erläutert die Datenbankanforderung und das Scope-Verhalten.

Reichen Azure-Budgetwarnungen oder AWS-Budgetwarnungen aus, um eine Budgetüberschreitung durch eine Anwendung zu verhindern?

Sie sind nützliche Absicherungen auf Provider-Kontoebene, entscheiden jedoch nicht darüber, ob eine bestimmte Gateway-Anfrage zugelassen werden soll. Behalten Sie die Abrechnungswarnungen der Provider bei und ergänzen Sie sie um ein getestetes Gateway-Budget sowie ein Produktlimit auf Anwendungsebene, wo der Anfragekontext bekannt ist.

Was sollte ich von einem fehlgeschlagenen LiteLLM-Aufruf speichern?

Speichern Sie den bereinigten Fehlertext, die normalisierte Ausnahmeklasse, den HTTP-Status, den Provider-Namen, das angeforderte Modell, den Zeitstempel, die Umgebung, die Client-Versuchsnummer und, falls verfügbar, x-litellm-call-id. Vermeiden Sie es, API-Schlüssel sowie sensible Prompt-/Antwortinhalte zu protokollieren.

Kann ein Fallback eine fehlerhafte Konfiguration verbergen?

Ja. Ein Fallback kann dazu führen, dass eine Kundenanfrage erfolgreich ist, während die primäre Route weiterhin fehlschlägt. Deshalb benötigen Fallback-Rate, routenspezifische Fehler, endgültige Modellgruppe, Latenz und Kosten Warnungen oder Dashboards. Behandeln Sie eine steigende Fallback-Rate als operatives Signal, nicht als abgeschlossene Behebung.

Fazit

Die dauerhafte Lösung für häufige LiteLLM-Fehler ist weder eine universelle Anzahl von Wiederholungsversuchen noch ein höheres Timeout. Sie besteht aus einem wiederholbaren Betriebszyklus: den tatsächlichen Fehler erfassen, die Richtlinienebene identifizieren, die kleinste sichere Änderung validieren und den Wiederherstellungspfad mit einem kontrollierten Test nachweisen. So bleiben Timeouts begrenzt, Budgetwarnungen aussagekräftig und Provider-Fehler sichtbar genug, um sie zu beheben.

Quellen

• LiteLLM-Zuordnung von Ausnahmen
• LiteLLM-Budgets und Ratenlimits
• LiteLLM-Provider-Failover und Fallbacks
• LiteLLM-Routing, Wiederholungsversuche, Cooldowns und Parallelität
• Best Practices für LiteLLM in der Produktion
• LiteLLM-Protokollierung
• LiteLLM-Prüfungen der Ausgabenerfassungsrate