Fehler der Grok API lassen sich grob in vier Gruppen teilen: Zugangsdaten und Rechte, Pfad und Modellname, Ratenbegrenzung und Kontingent sowie Netz und Timeout. Die Reihenfolge der Behandlung sollte sein: zuerst HTTP-Statuscode und Fehlertyp ansehen, dann die Request-ID, und erst zuletzt Prompt oder Modellparameter ändern. Ist die Reihenfolge umgekehrt, wird ein Konfigurationsproblem leicht als Modellproblem behandelt.

Dieser Artikel teilt die Fälle in 401, 404, 429 und Timeouts und nennt Ursachen, Prüfschritte und wiederverwendbaren Backoff-Code. Modelle und Preise richten sich nach den Modellpreisen.

Hinweis: xAI und Grok sind Marken der jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung. Fehlertypen und Schnittstellenverhalten können sich mit Versionen ändern; der Artikel beschreibt den Stand Oktober 2026, maßgeblich ist die offizielle xAI-Dokumentation.

1. Zuerst den Statuscode ansehen, nicht den Prompt ändern

Statuscode Bedeutung Wiederholen?
400 Parameter, Format oder Kontextlänge fehlerhaft Anfrage ändern, dann erneut
401 Key fehlt, ist falsch, ungültig oder passt nicht zur Adresse nicht wiederholen, Zugangsdaten korrigieren
403 Konto oder Key ohne Recht, regionale oder vertragliche Sperre nicht wiederholen, Rechte und Kontostatus prüfen
404 Pfad falsch oder Modellname existiert nicht nicht wiederholen, Adresse und Modellnamen prüfen
429 Anfragefrequenz, Parallelität oder Token überschritten nach Backoff wiederholen
500 interner Fehler des Upstream-Dienstes nach Backoff wiederholen
502 oder 503 Gateway oder Upstream vorübergehend nicht verfügbar nach Backoff wiederholen
504 Gateway wartet zu lange auf den Upstream Last senken und erneut versuchen

Die Request-ID aus der Antwort aufbewahren. Bei der Fehlersuche mit dem Anbieter ist eine Request-ID nützlicher als zehn Screenshots. Im Log mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname und Request-ID speichern, niemals den vollständigen Key oder sensible Inhalte.

2. 401: zuerst Header, dann Key prüfen

401 bedeutet, dass die Identität nicht bestätigt wurde; mit Guthaben oder Modellfähigkeit hat das nichts zu tun. Prüfung in dieser Reihenfolge:

  1. Ist der Header als Authorization: Bearer <Key> gesetzt? Der OpenAI-kompatible Einstieg von Grok verwendet nicht x-api-key.
  2. Stehen vor oder hinter dem Key Leerzeichen, Zeilenumbrüche oder Anführungszeichen? Die Kopie aus einem Chatfenster ist die häufigste Ursache.
  3. Stammen Key und Base URL vom selben Anbieter? Offizieller Key an Gateway-Adresse oder Gateway-Key an offizieller Adresse scheitert.
  4. Wurde der Key gesperrt, ist er abgelaufen, oder hat das zugehörige Projekt keine Aufrufrechte?
  5. Wurde die Umgebungsvariable wirklich geladen? Nur die ersten Zeichen ausgeben, nie den vollständigen Wert ins Log schreiben.
  6. Zeigt die Base URL auf die richtige Umgebung, und lautet der Pfad /v1/chat/completions?
export GROK_API_KEY="sk-dein-schluessel"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4",
    "messages": [{"role": "user", "content": "Antworte nur mit OK"}],
    "max_tokens": 16
  }'

Status 200 zeigt, dass Key, Adresse und Modellname stimmen. Bleibt es bei 401, denselben Key an einem anderen Einstieg testen; so lässt sich unterscheiden, ob der Key selbst oder die Gateway-Konfiguration bzw. Netzschicht das Problem ist.

3. 404: Pfad und Modellname getrennt prüfen

404 ist meist kein Key-Problem, sondern bedeutet „das Angefragte existiert nicht“. Vier häufige Ursachen:

  • Die Base URL enthält bereits /v1, und der Code hängt ein weiteres /v1 an, sodass /v1/v1/chat/completions entsteht.
  • Der Endpunkt ist als /completions oder /responses geschrieben, der Einstieg bietet aber nur Chat Completions.
  • Der Modellname ist falsch oder im Konto bzw. in der Gruppe nicht freigeschaltet.
  • Die Base URL endet mit einem Schrägstrich, wodurch beim Anhängen ein doppelter Schrägstrich oder ein falscher Pfad entsteht.

Prüfreihenfolge: Zuerst mit curl den in der offiziellen Dokumentation genannten Standardpfad aufrufen, dann den Modellnamen aus dem Kontrollzentrum oder den Modellpreisen kopieren. Modellnamen nicht aus dem Gedächtnis schreiben und nicht unverändert von anderen Plattformen übernehmen.

4. 429: Ratenbegrenzung ist kein fehlendes Guthaben

429 bedeutet, dass die Anfrage eine Rate- oder Kontingentgrenze überschreitet. Häufige Auslöser:

  • Anfragen pro Minute oder Token pro Minute überschritten.
  • Parallelität steigt plötzlich und füllt das Kontingent kurzfristig aus.
  • Mehrere Dienste teilen einen Key und verdrängen sich gegenseitig.
  • Wiederholungen ohne Backoff erzeugen mit jedem Fehlschlag mehr Last und einen Retry-Sturm.
  • Lange Ausgaben belegen viele Ausgabe-Token und lassen weniger Raum für Parallelität.
Symptom Mögliche Ursache Behandlung
429 gehäuft zur Spitzenzeit Verkehrsspitze Warteschlange, gleichmäßiger senden
429 bei einem Key für mehrere Dienste geteiltes Kontingent Keys je Projekt trennen
nach Wiederholungen schlimmer Retry ohne Backoff exponentielles Backoff mit Jitter
lange Anfragen zuerst 429 hoher Ausgabe-Token-Anteil max_tokens oder Parallelität senken

Zuerst retry-after aus der Antwort prüfen, falls vorhanden, und daraus die Wartezeit ableiten. Im SDK den Fehlertyp verwenden, nicht die Fehlermeldung als Zeichenkette vergleichen:

import random
import time
from openai import OpenAI, APIStatusError, RateLimitError

client = OpenAI(
    api_key="sk-dein-schluessel",
    base_url="https://ai.zhongshangqihang.com/v1",
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="grok-4",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, Versuch {attempt + 1}, warte {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, neuer Versuch in {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Wiederholungsversuche ausgeschöpft")

Wiederholungen sind nur bei vorübergehenden Fehlern sinnvoll. Bei Vorgängen mit bereits eingetretenen Nebenwirkungen zuerst mit Idempotenzschlüssel oder Statusabfrage klären, ob die Ausführung stattgefunden hat, und erst dann erneut senden.

5. Timeouts und Verbindungsfehler

Bei Timeouts ist zwischen Verbindungs- und Lese-Timeout zu unterscheiden. Ein Verbindungs-Timeout deutet meist auf Netz, DNS oder Proxy; ein Lese-Timeout auf lange Modellgenerierung, abgebrochene Streaming-Antworten oder eine zu kurze Idle-Zeit am Proxy.

Prüfreihenfolge:

  1. Mit curl time_namelookup, time_connect, time_appconnect und time_starttransfer erfassen und sehen, in welchem Abschnitt die Zeit verloren geht.
  2. Prüfen, ob der Proxy zu kurze Verbindungs- oder Idle-Timeouts setzt.
  3. Lange Ausgaben auf Streaming umstellen und während der Generierung lesen, statt auf die vollständige Antwort zu warten.
  4. Im Client getrennte Verbindungs- und Lese-Timeouts setzen, nicht ein sehr großes Gesamt-Timeout als Ersatz verwenden.
  5. Nach einem Timeout prüfen, ob die Anfrage bereits ausgeführt wurde, um doppelte Abrechnung oder doppelte Schreibvorgänge zu vermeiden.
export GROK_API_KEY="sk-dein-schluessel"

curl -o /dev/null -s \
  -w "code=%{http_code} dns=%{time_namelookup} connect=%{time_connect} tls=%{time_appconnect} ttfb=%{time_starttransfer} total=%{time_total}\n" \
  --max-time 120 \
  "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $GROK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-4","messages":[{"role":"user","content":"Antworte nur mit OK"}],"max_tokens":8}'

Sind DNS und Verbindung schnell, das erste Byte aber langsam, liegt das Problem meist in der Generierung oder beim Upstream. Scheitert bereits der Verbindungsaufbau, zuerst Ausgang und Proxy prüfen und nicht den Geschäftscode ändern.

6. Eine Tabelle zur Prüfreihenfolge

  1. Statuscode, Fehlertyp, Request-ID, Modellname und Zeitpunkt erfassen.
  2. Bei 401 und 403 Zugangsdaten, Kontostatus und Rechte prüfen; bei 404 Pfad und Modellnamen.
  3. Bei 400 Parameter, Kontextlänge, Bildformat und Größe des Request-Bodys prüfen.
  4. Bei 429 Kontingent, Parallelität, geteilte Keys und Retry-Stürme prüfen.
  5. Bei Timeouts schichtweise DNS, Verbindung, TLS, erstes Byte und Gesamtdauer betrachten.
  6. Bei 5xx zuerst mit Backoff wiederholen; bei anhaltendem Fehler den Anbieter mit Request-ID kontaktieren.
  7. Nach jeder Störung Monitoring und Alarme ergänzen, statt auf Nutzerrückmeldungen zu warten.

Häufige Fragen

Worin unterscheiden sich 429 und fehlendes Guthaben?

429 bedeutet, dass eine Rate- oder Kontingentgrenze überschritten wurde; eine Aufladung löst das nicht zwingend. Fehlendes Guthaben führt üblicherweise zu einem kontingent- oder abrechnungsbezogenen Fehler. Zuerst Fehlertyp und Rechnung prüfen, dann entscheiden, ob Warten, Senken der Parallelität oder Aufladen hilft.

Warum werden es mit Wiederholungen mehr 429?

Möglicherweise fehlt Backoff, die Parallelität ist zu hoch, oder mehrere Dienste teilen einen Key. Häufige Wiederholungen mit festem Intervall verstärken eine kleine Begrenzung zu einem Retry-Sturm. Exponentielles Backoff mit Jitter und eine maximale Anzahl verwenden.

Das Modell existiert doch, warum trotzdem 404?

Prüfen, ob die Base URL /v1 doppelt enthält und ob der Endpunkt /chat/completions lautet. Ist der Pfad korrekt, ist das Modell im Konto oder in der Gruppe möglicherweise nicht freigeschaltet, oder Schreibweise bzw. Versionssuffix stimmen nicht.

Darf nach einem Timeout einfach erneut gesendet werden?

Zuerst klären, ob die Anfrage ausgeführt wurde. Reine Leseabfragen lassen sich meist wiederholen; bei Schreibvorgängen, Abrechnung oder externen Nebenwirkungen einen Idempotenzschlüssel verwenden oder den Status abfragen.

Wie unterscheidet man Gateway- und Upstream-Fehler?

Zuerst Fehlertyp und Request-ID ansehen, dann dieselbe Anfrage einmal an den Gateway-Einstieg und einmal an den offiziellen Einstieg senden. So lässt sich schnell erkennen, ob Key, Netz, Gateway-Konfiguration oder Upstream die Ursache ist.

Nächster Schritt

Im ZSQH AI Gateway einen Test-Key anlegen und 401, 404, 429 sowie Timeout jeweils einmal durchspielen, bevor die Produktionsüberwachung angebunden wird. Verfügbarkeit und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: