Bevor Sie Llama-API-Fehler untersuchen, sollte eine Sache geklärt sein: Die öffentliche Vorschau der Llama API von Meta wurde am 6. Juli 2026 eingestellt. Wer die alte Adresse weiter aufruft, erhält häufig keine 401- oder 429-Antwort, sondern einen Hinweis auf die Einstellung oder eine Weiterleitung. Viele Diagnosen wie „Key ungültig“ oder „Modell existiert nicht“ betreffen in Wahrheit einen bereits abgeschalteten Endpunkt.

Heute werden Llama-Modelle in der Regel über Drittanbieter-Hosting, eigene Inferenzdienste oder ein einheitliches Gateway aufgerufen. Authentifizierung, Base URL, Modell-IDs, Ratenlimit-Regeln und Fehlerstrukturen unterscheiden sich je nach Plattform; eine universelle Fehlertabelle gibt es nicht. Dieser Artikel trennt 401, 404, 429, Timeouts und 400er-Fehler bei Tool-Aufrufen, nennt die Prüfreihenfolge und liefert wiederverwendbaren Fehlerbehandlungscode. Modelle und Preise entnehmen Sie bitte den Modellpreisen.

Hinweis: Llama ist eine Marke von Meta Platforms, Inc. Schnittstellen, Fehlercodes und Ratenlimit-Regeln der Hosting-Anbieter können sich mit Versionen ändern. Dieser Artikel beschreibt den Stand Oktober 2026; maßgeblich sind die offiziellen Dokumentationen der jeweiligen Plattform.

1. Zuerst klären, auf welcher Ebene der Fehler entsteht

Derselbe Fehlschlag kann völlig unterschiedliche Ursachen haben. Prüfen Sie zuerst Statuscode, Fehlertyp und Request-ID; erst danach entscheiden Sie, ob Konfiguration, Code oder Plattform geändert werden müssen.

Symptom Häufige Bedeutung Zuerst prüfen
Hinweis auf Einstellung oder Weiterleitung Anfrage erreicht einen abgeschalteten Endpunkt Domain und Base URL
401 Authentifizierung fehlgeschlagen Key, Request-Header, Plattform-Zuordnung
404 Pfad oder Modell existiert nicht Base URL, Pfad, Modell-ID
429 Ratenlimit oder Kontingent erreicht Parallelität, gemeinsam genutzter Key, Retry-Strategie
400 mit Hinweis auf context length Kontext überschritten Eingabelänge, Ausgabereserve
400 mit Hinweis auf tool oder JSON Ungültiges Tool-Aufrufformat Parameter-Schema, Parsing, Wiederholung
Timeout Verbindungs-, Erst-Token- oder Lese-Timeout Netzwerk, Eingabelänge, Timeout-Konfiguration
5xx Fehler des Upstream-Dienstes Backoff-Retry, Statusseite der Plattform

Im Log sollten mindestens Zeitpunkt, Plattform, Base URL, Modell-ID, Statuscode, Fehlertyp, Dauer und Request-ID stehen; vollständige Keys oder Nutzertexte gehören nicht ins Log.

2. 401: Key und Plattform müssen zusammenpassen

Ein 401 bedeutet, dass die Identität nicht bestätigt wurde; mit Modellfähigkeiten oder Guthaben hat das meist nichts zu tun. Für Llama gibt es keinen universellen Key: Ein Key der alten Meta-Plattform funktioniert nicht bei einem Drittanbieter und umgekehrt. Weitere häufige Ursachen:

  • Der Request-Header verwendet nicht Authorization: Bearer <key> oder enthält Schreib- bzw. Groß-/Kleinschreibfehler.
  • Vor oder nach dem Key stehen Leerzeichen, Zeilenumbrüche oder Anführungszeichen, besonders häufig beim Kopieren aus Chatfenstern.
  • Umgebungsvariablen wurden nicht tatsächlich geladen; die Deployment-Umgebung nutzt noch alte Werte.
  • Der Key wurde gelöscht, rotiert oder deaktiviert, während geplante Jobs weiter den alten Wert verwenden.
  • Ein Reverse Proxy oder Gateway überschreibt oder verwirft den Authorization-Header.
  • Kontostatus oder Regionsberechtigungen sind eingeschränkt: Der Key ist gültig, darf das Modell aber nicht aufrufen.

Senden Sie zuerst eine minimale curl-Anfrage und bestätigen Sie, dass Key, Base URL und Modell-ID gemeinsam funktionieren. Bei weiterhin 401 testen Sie mit einem neuen Key, um Probleme des Keys selbst von Proxy- und Gateway-Problemen zu trennen. Keys gehören weder fest in den Client-Code noch direkt in ein Frontend.

3. 404: Base URL, Modellname und abgeschaltete Endpunkte

Ein 404 bedeutet meist nicht, dass das Modell defekt ist, sondern dass die Anfrage an eine nicht vorhandene Adresse oder ein nicht vorhandenes Modell geht. Der häufigste Fall im Jahr 2026: Die frühere Meta-Adresse aus alten Tutorials ist abgeschaltet, und die Anfrage liefert 404 oder einen Einstellungshinweis. Weitere Ursachen:

  • Die Base URL gehört zu einer anderen Plattform oder enthält /v1 doppelt bzw. gar nicht.
  • Das SDK hängt automatisch /chat/completions an, während ein handgeschriebener Pfad dies ebenfalls tut.
  • Die Modell-ID stammt von der alten Plattform und wird vom neuen Hoster nicht erkannt.
  • Die Modell-ID benötigt ein Präfix oder Versionssuffix; Groß-/Kleinschreibung oder Bindestriche weichen ab.
  • Das Modell ist in der Zielregion nicht verfügbar oder wurde von der Plattform entfernt.
  • Rewrite-Regeln eines Reverse Proxy beschädigen den Pfad.

Die Modellnamen unterscheiden sich zwischen Plattformen erheblich. Pflegen Sie deshalb eine Mapping-Tabelle in der Konfiguration statt verstreuter Modellnamen im Code. Beim Wechsel ändern Sie nur Mapping und Base URL. Prüfen Sie bei 404 zuerst den Modellkatalog und dann den Pfad; Wiederholungen lösen das Problem nicht.

4. 429: Ratenlimits, Kontingente und Retry-Stürme

Ein 429 zeigt an, dass Anfragen ein Rate-, Parallelitäts- oder Kontingentlimit überschreiten. Die Regeln unterscheiden sich je nach Hoster: Requests pro Minute, Tokens pro Minute, Tageskontingent oder Kontostufe; maßgeblich ist die Plattformdokumentation. Typische Szenarien:

  • Mehrere Dienste teilen sich einen Key und konkurrieren um dasselbe Kontingent.
  • Batch-Jobs starten zur vollen Stunde gleichzeitig und erzeugen eine Lastspitze.
  • Wiederholungen erfolgen ohne Backoff und verstärken den Fehler zu einem Retry-Sturm.
  • Lange Kontexte oder lange Ausgaben verbrauchen viele Tokens und verringern den Spielraum für Parallelität.
  • Nach Aufbrauchen eines kostenlosen oder Testkontingents antwortet die Plattform weiterhin mit 429 oder einem ähnlichen Fehler.

Reihenfolge der Behandlung: zuerst Parallelität senken, dann exponentielles Backoff mit zufälligem Jitter ergänzen und erst zuletzt Keys aufteilen oder Kontingente erhöhen. Das Aufteilen von Keys löst nur Konflikte bei gemeinsamer Nutzung, nicht eine Überschreitung des Gesamtvolumens. Das Monitoring sollte 429-Anteile getrennt nach Plattform, Modell und Projekt erfassen; sonst lässt sich kaum feststellen, welcher Aufrufer das Kontingent verbraucht.

5. Timeouts: Verbindung, erstes Token, Lesen und Streaming

Ein Timeout bedeutet nicht automatisch, dass der Dienst nicht verfügbar ist. Bestimmen Sie zuerst, an welcher Stelle es hängt:

  • Verbindungs-Timeout: DNS, Ausgang oder Proxy nicht erreichbar; die Anfrage erreicht die Plattform noch nicht.
  • Langsames erstes Token: Eingabe zu lang, Warteschlange der Plattform oder hohe Modelllast.
  • Lese-Timeout: Ausgabe zu lang, Inferenz dauert lange oder eine Zwischenkomponente trennt die Verbindung.
  • Streaming-Abbruch: Netzwerkschwankung oder Proxy unterbricht den Stream; nur ein Teil des Inhalts kommt an.
  • Gleichzeitige Timeouts auf der gesamten Seite: lokaler Ausgang oder Upstream gestört; zuerst die Statusseite prüfen.

Verbindungs- und Lese-Timeout sollten getrennt konfiguriert werden. Ein sehr großer gemeinsamer Wert blockiert bei Störungen den Thread-Pool; ein zu kleiner Wert bricht normale lange Aufgaben ab. Streaming-Schnittstellen sollten empfangene Inhalte und die Abbruchstelle protokollieren, Wiederverbindung und Deduplizierung unterstützen und keine halben Inhalte in die Datenbank schreiben.

6. 400: Kontextüberschreitung und Tool-Aufrufformat

Der Status 400 deckt ein breites Spektrum ab; achten Sie zuerst auf Schlüsselwörter in der Fehlermeldung. Hinweise auf context length, maximum tokens oder input too long bedeuten meist eine Kontextüberschreitung: Eingabe plus Ausgabereserve überschreiten das Modelllimit. Gegenmaßnahmen sind Token zählen, Verlauf kürzen, abgerufene Inhalte komprimieren oder ein Modell mit größerem Kontext wählen. Erhöhen Sie nicht einfach max_tokens, denn das verringert den Platz für die Eingabe.

Hinweise auf tool, function, arguments oder JSON deuten auf ein ungültiges Tool-Aufrufformat: nicht parsebares JSON, fehlende Pflichtfelder, falsche Parametertypen oder einen unbekannten Toolnamen. Grundregeln:

  1. Parameter mit JSON Schema validieren, nicht per String-Verkettung erzeugen.
  2. Bei Parse-Fehlern die Fehlermeldung und das erwartete Format an das Modell zurückgeben und es einmal korrigieren lassen.
  3. Die Zahl der Korrekturversuche begrenzen, um Endlosschleifen zu vermeiden.
  4. Die Rohantwort protokollieren, um Modell- von Prompt-Problemen zu unterscheiden.
  5. Risikoreiche Tools zusätzlich prüfen; verlassen Sie sich nicht darauf, dass das Modell „ausgeführt“ meldet.

7. Wiederverwendbarer Fehlerbehandlungscode

Das Beispiel nutzt eine OpenAI-kompatible Schnittstelle; Base URL und Modell-ID werden aus Umgebungsvariablen gelesen. Die automatische Wiederholung des SDK ist deaktiviert, damit sie sich nicht mit dem eigenen Backoff überlagert.

import os
import random
import time
import logging
from openai import (
    OpenAI, AuthenticationError, NotFoundError, RateLimitError,
    BadRequestError, APITimeoutError, APIStatusError,
)

logging.basicConfig(level=logging.INFO)
client = OpenAI(
    api_key=os.environ["LLAMA_HOST_API_KEY"],
    base_url=os.environ["LLAMA_HOST_BASE_URL"],  # Kompatible Adresse des jeweiligen Hosters
    max_retries=0,
    timeout=90,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["LLAMA_MODEL_ID"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except AuthenticationError:
            raise  # Key und Plattform passen nicht zusammen; Wiederholen ist sinnlos
        except NotFoundError as exc:
            logging.error("Base URL und Modell-ID prüfen: %s", exc.request_id)
            raise
        except BadRequestError as exc:
            logging.error("Parameter, Kontext oder Tool-Format fehlerhaft: %s", exc.request_id)
            raise
        except (RateLimitError, APITimeoutError) as exc:
            wait = min(2 ** attempt, 20) + random.random()
            logging.warning("Versuch %s fehlgeschlagen, neuer Versuch in %.1f Sekunden: %s",
                            attempt + 1, wait, exc.request_id)
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                logging.warning("Upstream %s, neuer Versuch in %.1f Sekunden", exc.status_code, wait)
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Wiederholungen aufgebraucht; Ratenlimit- und Timeout-Konfiguration prüfen")

Wiederholungen eignen sich nur für vorübergehende Fehler. Bei 401, 404 und den meisten 400ern wird es nicht besser; stattdessen wachsen Log und Rechnung. Bei Geschäftsvorgängen mit Nebenwirkungen prüfen Sie per Idempotenzschlüssel oder Statusabfrage, ob die Aktion bereits ausgeführt wurde.

8. Logs, Monitoring und Prüfreihenfolge

Arbeiten Sie die folgende Reihenfolge ab, statt sofort das Modell zu wechseln:

  1. Statuscode, Fehlertyp, Request-ID, Plattform, Base URL, Modell-ID und Zeitpunkt protokollieren.
  2. Wenn Anfragen noch an die alte Llama-API-Adresse gehen, zuerst die Migration abschließen.
  3. Bei 401 Key, Request-Header, Umgebungsvariablen und Plattform-Zuordnung prüfen.
  4. Bei 404 Base URL, /v1-Pfad und aktuellen Modellkatalog prüfen.
  5. Bei 429 Parallelität, gemeinsam genutzte Keys, Retry-Strategie und Spitzenzeiten prüfen.
  6. Bei Timeouts DNS, Proxy, Eingabelänge, Erst-Token-Zeit und Lese-Timeout prüfen.
  7. Bei 400 Kontextlänge, Parameterunterstützung und Tool-Schema prüfen.
  8. Bei 5xx zunächst mit Backoff wiederholen; bei anhaltenden Fehlern mit Request-ID an die Plattform wenden.

Das Monitoring sollte 401, 404, 429, Timeouts und 5xx mindestens stündlich und getrennt nach Plattform und Modell zählen. Steigt die Fehlerquote sprunghaft, prüfen Sie zuerst, ob sich die Fälle auf ein Projekt, einen Key oder ein Modell konzentrieren; danach entscheiden Sie über geringere Parallelität, Kanalwechsel oder Rollback.

Häufige Fragen

Bedeutet ein 401 der Llama API, dass der Key abgelaufen ist?

Nicht unbedingt. Am häufigsten passt der Key nicht zur Plattform, etwa ein Key der alten Meta-Plattform bei einem Drittanbieter oder umgekehrt. Prüfen Sie Request-Header, Umgebungsvariablen und die zugehörige Plattform und testen Sie dann mit einer minimalen Anfrage.

Warum liefert ein Wechsel des Hosters plötzlich 404?

Die Modell-ID hat sich geändert. Benennung, Präfixe, Versionssuffixe und verfügbare Regionen unterscheiden sich; alte Modellnamen existieren auf der neuen Plattform meist nicht. Legen Sie eine Mapping-Tabelle an und orientieren Sie sich am Modellkatalog der neuen Plattform.

Sollte man bei 429 sofort wiederholen?

Nicht sofort in dichten Abständen. Senken Sie zuerst die Parallelität, dann exponentielles Backoff mit Jitter und einer Obergrenze. Anhaltende 429er zeigen, dass Gesamtvolumen oder Kontingent nicht ausreichen; dann sind Key-Aufteilung, Lastverteilung über Zeiten oder eine Kontingentanpassung nötig.

Kann man bei Timeouts unbegrenzt wiederholen?

Nein. Wiederholungen brauchen eine Obergrenze, Backoff und Alarmierung. Ein Timeout kann außerdem bedeuten, dass die Anfrage beim Upstream bereits läuft; bei Vorgängen mit Nebenwirkungen prüfen Sie zuerst den Status, bevor Sie erneut senden.

Was tun, wenn das JSON der Tool-Parameter nicht parsebar ist?

Zuerst mit JSON Schema validieren und die Rohantwort aufbewahren; dann Fehlermeldung und erwartetes Format an das Modell zurückgeben und es einmal korrigieren lassen, mit begrenzter Anzahl. Risikoreiche Tools zusätzlich prüfen; eine Erfolgsmeldung des Modells allein genügt nicht.

Nächste Schritte

Erstellen Sie zunächst im ZSQH AI Gateway einen Test-Key und spielen Sie 401, 404, 429, Timeout und einen fehlgeschlagenen Tool-Aufruf je einmal durch, bevor Sie das Produktionsmonitoring anbinden. Verfügbarkeit und Preise der Modelle entnehmen Sie den Modellpreisen.

Weiterlesen: