OpenAI API Fehler und Rate-Limits: 401, 404, 429, 5xx (2026)

Die Fehler der OpenAI API wirken vielfältig, doch entscheidend sind zunächst nur fünf Ebenen: Wurde der Request überhaupt gesendet, stimmt die Identität, stimmen Adresse und Modell, sind die Parameter gültig, und wurden Kontingent oder Rate-Limit erreicht. Wer in dieser Reihenfolge prüft, lokalisiert die meisten Probleme innerhalb weniger Minuten.

Dieser Artikel erklärt 401, 403, 404, 400, 429 und 5xx nach Statuscode und liefert minimale Reproduktionsbefehle, eine Retry-Strategie und eine feste Prüfreihenfolge. Modellnamen und Gateway-Konfiguration richten sich nach den Modellpreisen und der Integrationsdokumentation auf dieser Website.

Hinweis: OpenAI, GPT und ChatGPT sind Marken ihrer jeweiligen Inhaber. Dieser Artikel beschreibt übliches Schnittstellenverhalten im Oktober 2026; Fehlercodes und Limitregeln richten sich nach der offiziellen Dokumentation und der tatsächlichen Antwort.

1. Zuerst drei Belege sichern

Vor der Fehlersuche sollten Sie drei Dinge speichern:

den HTTP-Statuscode;
error.type, error.code und error.message im Antwortkörper;
die x-request-id im Antwortheader.

Die Request-ID ist die nützlichste Information bei der Kommunikation mit dem Anbieter. Ohne sie lässt sich nur „irgendwann ist ein Aufruf fehlgeschlagen“ sagen; mit ihr lassen sich der konkrete Request, das konkrete Upstream und die konkrete Abrechnung nachvollziehen.

Statuscode	Häufiger Typ	Erste Einschätzung
400	`invalid_request_error`	Problem mit Parametern, JSON oder Kontextlänge
401	`authentication_error`	Key fehlt, ist falsch oder ungültig
403	`permission_error`	Key hat keine Rechte für Modell oder Projekt
404	`not_found_error`	Base URL oder Modellname falsch
429	`rate_limit_error` / `insufficient_quota`	Rate-Limit oder unzureichendes Guthaben
500/502/503/504	`server_error`	Upstream-Störung oder Netzunterbrechung

2. 401 und 403: Identität und Rechte

Bei 401 erkennt der Server den Key nicht. Häufige Ursachen:

Der Header enthält kein Authorization: Bearer;
beim Kopieren des Keys sind Leerzeichen, Zeilenumbrüche oder eine Kürzung entstanden;
der Key wurde gelöscht, rotiert oder das zugehörige Projekt wurde deaktiviert;
ein Gateway-Key wurde an die offizielle Adresse gesendet oder ein offizieller Key an das Gateway;
der Umgebungsvariablenname ist falsch geschrieben, tatsächlich wird eine leere Zeichenkette gesendet.

403 bedeutet eher „ich erkenne dich, aber du darfst das nicht“. Beispielsweise fehlt dem Key die Berechtigung für das Modell, die Organisation ist eingeschränkt oder das Projekt hat die Funktion nicht freigeschaltet. Bei 403 nicht wiederholt versuchen, sondern zuerst Projektzugehörigkeit des Keys und Modellrechte in der Konsole prüfen.

Ein schneller Selbsttest:

curl -sS "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

Werden Modelle aufgelistet, sind Key und Adresse grundsätzlich korrekt; bei weiterhin 401 prüfen Sie zuerst den Key selbst und die Umgebungsvariable.

3. 404: Adresse oder Modell existiert nicht

404 bedeutet nicht zwingend, dass die Schnittstelle abgeschaltet wurde; meist ist der Pfad falsch zusammengesetzt. Häufige Fälle:

Symptom	Ursache	Behandlung
`404 page not found`	Base URL hat ein `/v1` zu viel oder zu wenig	Einheitlich `https://api.zhongshangqihang.com/v1` verwenden
`model_not_found`	Modellname falsch geschrieben oder nicht freigeschaltet	Modellnamen von der Modellpreis-Seite kopieren
404 bei doppeltem Schrägstrich im Pfad	Beim Zusammensetzen wurde ein `/` zu viel erzeugt	Doppelte Schrägstriche entfernen
SDK meldet 404	`base_url` und Schnittstellenpfad überschneiden sich	Nur ein `/v1` behalten

Senden Sie zur Prüfung zuerst einen minimalen Request mit curl, um Probleme der URL-Zusammensetzung im SDK auszuschließen. Funktioniert curl, das SDK aber nicht, liegt die Ursache meist bei base_url, Proxy oder SDK-Version.

4. 400: Parameter und Kontext

400 bedeutet, dass der Request selbst ungültig ist; Wiederholen bringt nichts. Häufige Ursachen:

fehlerhaftes JSON, etwa nachgestellte Kommas, einfache Anführungszeichen oder nicht escapte Zeilenumbrüche;
Parameter, die das Modell nicht unterstützt, etwa bestimmte Sampling-Parameter;
max_tokens über dem Modellmaximum;
Input über dem Kontextfenster, Rückgabe context_length_exceeded;
Bildformat, -größe oder nicht erreichbare Bild-URL;
ungültiges Tool-Schema mit fehlenden Pflichtfeldern.

Vorgehen: zuerst auf den minimalen Request reduzieren, dann Parameter einzeln wieder hinzufügen. Ändern Sie nicht fünf Stellen gleichzeitig, sonst ist nach dem Verschwinden des Fehlers unklar, welche Änderung gewirkt hat.

5. 429: Rate-Limit oder zu wenig Guthaben

429 wird am häufigsten falsch gedeutet. Es hat mindestens zwei Bedeutungen:

Fehlercode	Bedeutung	Behandlung
`rate_limit_exceeded`	Request-Frequenz, Token-Rate oder Parallelität überschritten	Parallelität senken, Warteschlange, exponentielles Backoff
`insufficient_quota`	Guthaben oder Kontingent erschöpft	Aufladen, Key wechseln, Projektkontingent prüfen

Prüfen Sie zuerst Antwortkörper und Header. retry-after nennt die empfohlene Wartezeit; x-ratelimit-remaining-requests und x-ratelimit-remaining-tokens zeigen den Rest. Ist der Rest 0, hilft längeres Backoff nicht; dann muss das Fenster zurückgesetzt oder das Limit erhöht werden.

Eine brauchbare Retry-Logik:

import random
import time
from openai import OpenAI

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

def chat(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="gpt-5.5",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=500,
                timeout=60,
            )
            return resp.choices[0].message.content
        except Exception as exc:
            status = getattr(exc, "status_code", None)
            if status not in (429, 500, 502, 503, 504) or attempt == retries - 1:
                raise
            wait = min(2 ** attempt, 16) + random.random()
            print(f"{status}, neuer Versuch in {wait:.1f} Sekunden: {exc}")
            time.sleep(wait)
    raise RuntimeError("unreachable")

Wiederholungen helfen nur bei 429, 5xx und Netzfehlern. Bei 400, 401, 403 und 404 verschwenden sie Zeit und Kontingent.

6. 5xx: Upstream-Störung und Netzprobleme

500, 502, 503 und 504 bedeuten meist nicht, dass der Request falsch war, sondern dass der Upstream gestört ist, das Gateway ein Timeout hat oder das Netz unterbrochen wurde. Grundsätze:

Ein- bis zweimal mit exponentiellem Backoff und Jitter wiederholen;
bei Streaming prüfen, ob bereits Teile empfangen wurden; Teilausgaben können schon abgerechnet sein;
idempotente Vorgänge dürfen automatisch wiederholt werden, nicht-idempotente brauchen einen Deduplizierungsschlüssel;
bei großflächigen 5xx die Statusseite des Anbieters prüfen und nicht blind die Parallelität erhöhen;
Request-ID protokollieren, damit der Anbieter die Ursache finden kann.

Sind nur Ihre Requests von 5xx betroffen und andere Teams nicht, prüfen Sie zuerst Request-Größe, Timeout-Einstellungen und Proxy-Kette.

7. Eine feste Prüfreihenfolge

Bei Fehlern gehen Sie der Reihe nach vor, ohne Schritte zu überspringen:

Minimalen Request mit curl senden und Adresse sowie Key prüfen.
Offizielle Adresse und Gateway-Adresse vergleichen, um Key-Vermischung auszuschließen.
Prüfen, ob die Base URL nur ein /v1 enthält.
Prüfen, ob der Modellname von der Preisseite stammt und freigeschaltet ist.
Optionale Parameter entfernen und bestätigen, dass der minimale Request funktioniert.
Guthaben, Projektkontingent und Key-Obergrenze prüfen.
429-Header prüfen und Rate-Limit von Guthabenmangel unterscheiden.
Statusseite des Anbieters auf Upstream-Störungen prüfen.
Request-ID, Statuscode und Antwortkörper speichern und dann den Support kontaktieren.

8. Häufige Fragen

Bedeutet 429 immer, dass zu schnell aufgerufen wurde?

Nein. 429 kann eine Frequenz- oder Parallelitätsüberschreitung sein, aber auch auf zu wenig Guthaben hinweisen. Prüfen Sie error.code und die Header und drosseln Sie nicht pauschal.

Reicht bei 401 ein anderer Key?

Ein anderer Key schließt ein Problem des Keys selbst aus. Bei vermischten Adressen, leerer Umgebungsvariable oder fehlenden Projektrechten hilft jedoch kein anderer Key. Prüfen Sie zuerst, wohin der Request tatsächlich gesendet wird.

Ist 404 ein abgeschaltetes Modell?

Meist ist die Base URL oder der Modellname falsch. Rufen Sie zuerst /v1/models per curl auf und gleichen Sie den Modellnamen mit der Preisseite ab.

Darf bei 5xx unbegrenzt wiederholt werden?

Nein. Setzen Sie maximale Versuche und ein Gesamt-Timeout, damit sich während einer Störung keine Requests stapeln. Bei Streaming ist zu berücksichtigen, dass Teilausgaben bereits abgerechnet sein können.

Wie unterscheidet man Gateway-Fehler von offiziellen Fehlern?

Vergleichen Sie Antwortformat und Request-ID und senden Sie denselben Key und dasselbe Modell einmal an die offizielle Adresse und einmal an das Gateway. Die Ebene, die sich stabil reproduzieren lässt, ist die Problemquelle.

Nächster Schritt

Richten Sie zuerst minimalen Request, Usage-Log und Retry-Strategie ein, bevor Sie Geschäftstraffic anschließen. Für RMB-Aufladung und einen einheitlichen Multi-Modell-Zugang können Sie sich für das ZSQH AI Gateway registrieren; Modellnamen und Preise richten sich nach den Modellpreisen.

Weiterlesen: