Kimi API Fehler und Rate-Limits: 401, 404, 429 und Timeouts (2026)

Bei Fehlern der Kimi API prüfen Sie zuerst drei Dinge: HTTP-Statuscode, error.type und request_id. Ein 429 kann Serverüberlast, ein Organisations-Rate-Limit oder zu niedriges Guthaben bedeuten; ein 401 kann ein falsch geschriebener Key oder die Vermischung von China- und internationaler Seite sein. Erst klassifizieren, dann Code ändern.

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

Hinweis: Moonshot und Kimi sind Marken ihrer jeweiligen Inhaber. Fehlertypen, Rate-Limit-Regeln und Schnittstellenverhalten können sich ändern; der Artikel beschreibt die übliche Lage mit Stand Oktober 2026, maßgeblich ist die offizielle Dokumentation.

1. Statuscodes im Überblick

Status	Fehlertyp	Übliche Bedeutung	Richtung
400	`invalid_request_error`	Parameterfehler, Kontext zu lang, Ausgabegrenze überschritten	Anfrage ändern
400	`content_filter`	Ein- oder Ausgabe gegen Inhaltssicherheit	Prompt anpassen
401	`invalid_authentication_error`	Key ungültig, Region passt nicht	Zugangsdaten korrigieren
401	`incorrect_api_key_error`	Key fehlt oder ist falsch	Zugangsdaten korrigieren
403	`permission_denied_error`	Schnittstelle nicht freigeschaltet, IP-Whitelist, Guthaben oder Rechte	Rechte und Guthaben prüfen
404	`resource_not_found_error`	Modellname oder Pfad falsch	Modellliste prüfen
429	`engine_overloaded_error`	Serverüberlast	Backoff und Retry
429	`rate_limit_reached_error`	Parallelität, RPM, TPM oder TPD überschritten	Drosseln oder Quote erhöhen
429	`exceeded_current_quota_error`	Zahlungsrückstand, zu wenig Guthaben, Gutschein abgelaufen	Aufladen
499	`client_closed_request`	Client oder Proxy trennt vorzeitig	Timeout und Streaming prüfen
500	`server_error`	Interner Serverfehler	Backoff und Retry
503	`server_unavailable`	Dienst vorübergehend nicht verfügbar	Backoff und Retry
504	`Gateway Time-out`	Lange Anfrage zu lange wartend	Auf Streaming umstellen

Zu niedriges Guthaben kann je nach Zugang als 403 oder 429 erscheinen; verlassen Sie sich nicht nur auf den Statuscode, sondern auf error.type. Im Log mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname und request_id erfassen; vollständige Keys und sensible Inhalte nicht protokollieren.

2. 401: erst Region, dann Key

Gehört der Key der China-Seite zur Adresse der internationalen Seite oder umgekehrt? Konten, Guthaben und Keys beider Seiten sind vollständig getrennt.
Wurden Keys verschiedener Produktlinien gemischt, etwa Open Platform, Kimi Code und Mitgliedschaft?
Enthält der Key führende oder nachfolgende Leerzeichen, Zeilenumbrüche oder zusätzliche Anführungszeichen?
Wurde die Umgebungsvariable tatsächlich geladen? Testweise nur das Präfix ausgeben.
Wurde der Key gelöscht, rotiert oder hat er keine Berechtigung für das aktuelle Projekt?
Lautet der Header Authorization: Bearer <key> und der Pfad /v1/chat/completions?

export MOONSHOT_API_KEY="IHR_SCHLUESSEL"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "Antworte nur mit OK"}]
  }'

Liefert dieser Befehl 200, stimmen Key, Region und Modellname. Kommt weiterhin 401, mit einem bekannt funktionierenden Key gegentesten, um Key und Gateway-Konfiguration zu unterscheiden.

3. 404: Modellname und base_url sind die häufigsten Fehler

Ein 404 bedeutet nicht zwingend, dass das Modell abgeschaltet wurde. Vier Ursachen sind typisch:

Beim OpenAI SDK wurde keine base_url gesetzt, die Anfrage ging an die Standardadresse von OpenAI und das Modell existiert dort nicht.
Der Modellname ist falsch geschrieben, oder das Konto hat keinen Zugriff auf diesen Typ.
Der Pfad enthält /v1 doppelt oder gar nicht, oder der Chat-Pfad wurde anders geschrieben.
China- und internationale Seite haben unterschiedliche Modellnamen und Berechtigungen.

Zuerst mit demselben Key die Modellliste abrufen und prüfen, was das Konto sieht:

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

Modelle, die nicht in der Liste stehen, nicht erraten. Maßgeblich sind die tatsächliche Antwort des Kontos und unsere Modellpreise. Liefert die Modellliste Ergebnisse, der Chat aber weiterhin 404, prüfen Sie, ob im Pfad /v1 fehlt oder ob der Client base_url und vollständigen Pfad doppelt zusammensetzt.

4. 429: drei Typen, drei Reaktionen

`error.type`	Bedeutung	Retry sinnvoll	Vorgehen
`engine_overloaded_error`	Serverüberlast	Ja	Nach `Retry-After` zurückweichen, Parallelität senken
`rate_limit_reached_error`	Parallelität, RPM, TPM, TPD auf Organisationsebene überschritten	Teilweise	Drosseln, Keys trennen, Stufe erhöhen
`exceeded_current_quota_error`	Rückstand, Guthaben zu niedrig, Gutschein abgelaufen	Nein	Aufladen oder Abrechnung prüfen

Bei überschrittenem TPD hilft meist nur Warten bis zum nächsten Tag oder eine höhere Quote; weitere Retries sind sinnlos. Durch 429 unterbrochene Anfragen werden üblicherweise nicht berechnet, erfolgreiche Wiederholungen dagegen normal. Weder aus Angst vor Kosten endlos wiederholen noch aus einem 429 schließen, das Konto sei bereits belastet. Das OpenAI SDK wiederholt standardmäßig automatisch und kann einen 429 in mehrere Anfragen vervielfachen; im Produktivbetrieb max_retries explizit setzen und eigene Backoff-Logik verwenden.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="IHR_SCHLUESSEL",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("Guthaben oder Kontingent erschöpft, bitte aufladen")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "warte", round(wait, 1), "Sekunden")
            time.sleep(wait)
    raise RuntimeError("Maximale Wiederholungszahl erreicht")

Retries eignen sich nur für vorübergehende Fehler. Bei Vorgängen mit Nebenwirkungen zuerst mit Idempotenzschlüssel oder Statusprüfung feststellen, ob die Aktion bereits ausgeführt wurde, und erst dann erneut senden.

5. Timeouts und 504

Lange Textgenerierung, die Analyse langer Dokumente und Coding-Agenten laufen am häufigsten in Timeouts. Die Reihenfolge der Behandlung:

Nicht gestreamte Anfragen auf stream=True umstellen, damit die Verbindung kontinuierlich Daten liefert.
Sinnvolle Verbindungs- und Lese-Timeouts setzen, nicht die SDK-Standardwerte übernehmen.
Prüfen, ob Firmenproxy, Gateway oder lokale Routing-Tools die Verbindung vorzeitig trennen; das kann sich als 499 zeigen.
Mit max_completion_tokens die Ausgabelänge pro Anfrage begrenzen und sehr lange Aufgaben aufteilen.
Request-ID und Dauer jedes Timeouts erfassen, um langsames Modell, Netz oder Gateway zu unterscheiden.

stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "Schreibe eine Checkliste für die Bereitstellung"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Streaming senkt den Stückpreis nicht, reduziert aber deutlich die Verschwendung durch „bis zum Timeout warten und dann wiederholen“. Der Verbindungs-Timeout darf kurz sein, der Lese-Timeout muss sich an der längsten Generierungszeit orientieren; im Streaming nicht den Lese-Timeout des nicht gestreamten Betriebs übernehmen, sonst trennt der Client eine normale Generierung selbst.

6. Diagnosereihenfolge

Statuscode, error.type, request_id, Modellname und Zeitpunkt erfassen.
Bei 401 und 403 Region, Key, Produktlinie, Rechte und Guthaben prüfen.
Bei 404 base_url, Modellname und Kontorechte prüfen und mit der Modellliste verifizieren.
Bei 400 Kontextlänge, Ausgabegrenze, Dateiformat und Inhaltssicherheit prüfen.
Bei 429 nach error.type in Überlast, Rate-Limit und Zahlungsrückstand trennen.
Bei 499 und 504 Streaming, Timeouts, Proxy und Verbindungshaltung prüfen.
Bei 500 und 503 mit Backoff wiederholen; bei Dauerhaftigkeit request_id an den Anbieter geben.
Nach jedem Vorfall Monitoring und Alarme ergänzen, nicht auf Nutzerfeedback warten.

Häufige Fragen

Worin unterscheiden sich 429 und 503?

429 kann Serverüberlast oder ein Konto-/Guthabenproblem sein; zuerst error.type prüfen. 503 bedeutet vorübergehende Nichtverfügbarkeit und wird meist nach Backoff wiederholt. Gemeinsam ist: nicht in festem Takt heftig wiederholen.

Was tun, wenn nach dem Aufladen weiterhin 401 kommt?

Prüfen Sie, ob Aufladung und Key zur selben Region und Produktlinie gehören. Testen Sie mit einem neu erstellten Key, um einen gelöschten alten Key oder zwischengespeicherte Umgebungsvariablen auszuschließen.

Welcher Fehler erscheint bei zu langem Kontext?

Meist 400 invalid_request_error mit dem Hinweis, dass die Eingabe-Token zu lang sind. Eingabe kürzen, Verlauf beschneiden oder ein Modell mit größerem Kontext verwenden.

Sollte die automatische SDK-Wiederholung aktiviert bleiben?

Sie kann aktiviert werden, braucht aber eine Obergrenze. Standard-Retries können 429 vervielfachen; im Produktivbetrieb besser deaktivieren und nach Fehlertyp eigene Backoff-Logik und Alarme einsetzen.

Wie unterscheidet man Gateway-Fehler von Anbieterfehlern?

Dieselbe Anfrage gegen Direktverbindung und Gateway senden und Statuscode, error.type und request_id vergleichen. So lässt sich schnell erkennen, ob Upstream, Netz, Key oder Gateway-Konfiguration betroffen ist.

Nächster Schritt

Erstellen Sie im ZSQH AI Gateway einen Test-Key und spielen Sie 401, 404, 429 und Timeout je einmal durch, bevor Sie das Produktionsmonitoring anbinden. Modellverfügbarkeit und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: