Fehler der MiniMax API lassen sich grob in vier Ebenen teilen: HTTP-Statuscodes, Geschäftscodes im Antwortkörper, Timeouts auf Transportebene und Störungen des Upstream-Dienstes. Bei der Diagnose sollte man erst die Ebene bestimmen und dann eingrenzen, statt sofort Prompts umzuschreiben oder das Modell zu wechseln. Viele Fälle, die wie „das Modell taugt nichts“ aussehen, entpuppen sich am Ende als falsch konfigurierter Key, vermischte Adressen oder zu kurze Timeouts.

Dieser Artikel trennt 401, 403, 404, 429, 5xx und Timeouts, nennt Ursachen, Prüfreihenfolge und wiederverwendbaren Fehlerbehandlungscode. Modellnamen, Preise und Kontingente richten sich nach der offiziellen Dokumentation und unseren Modellpreisen.

Hinweis: MiniMax ist eine Marke ihrer jeweiligen Inhaber. Fehlercodes, Limitstufen und Schnittstellenverhalten können sich mit Versionen ändern; der Artikel beschreibt die übliche Lage mit Stand Oktober 2026, maßgeblich ist die offizielle MiniMax-Dokumentation.

1. Zuerst die Ebenen trennen: Statuscode, Geschäftscode, Timeout

Die offizielle Fehlercode-Dokumentation listet Geschäftscodes separat auf und empfiehlt, bei Rückmeldungen die trace_id aus dem Antwortheader mitzuliefern. Die Rate-Limit-Dokumentation begrenzt über drei Dimensionen: RPM, TPM und parallele Aufgaben. Bei der Diagnose müssen HTTP-Ebene und Geschäftsebene gemeinsam betrachtet werden: Einige native Schnittstellen liefern HTTP 200, während der Fehler im Antwortkörper unter base_resp steht; OpenAI-kompatible Zugänge drücken Fehler üblicherweise über den HTTP-Status aus. Beide Ebenen protokollieren, damit keine Fehldiagnose entsteht.

Symptom Häufige Bedeutung Zuerst prüfen Behandlung
401, 1004, 2049 Authentifizierung fehlgeschlagen oder Key ungültig Key, Bearer-Header, passende Adresse Neuen Key für eine Minimalanfrage verwenden
403 Rechte, Kontostatus oder Zugangsbeschränkung Modellrechte, Verifizierungsstatus, Gateway-Kontingent Konsole und Antwortkörper abgleichen
404 Pfad oder Modell existiert nicht Base URL, /v1, Modell abgeschaltet Offizielle Modellliste prüfen
400, 2013, 1039 Parameterfehler oder Token-Überschreitung thinking, temperature, max_tokens Parameter laut Dokumentation begrenzen
429, 1002, 2045, 1041, 2056 Rate-Limit, Parallelität oder Tariffenster begrenzt RPM, TPM, geteilte Keys, Verkehrsspitzen Backoff, Warteschlange, Keys trennen
1008 Guthaben unzureichend Kontostand, Abonnementkontingent Aufladen oder Abrechnungsart wechseln
Timeout, 1001 Verbindungs- oder Lese-Timeout Netz, Proxy, lange Ausgabe, Streaming Timeouts getrennt setzen
5xx, 1024, 1033 Upstream-Störung Dienststatus, Wiederholbarkeit der Anfrage Begrenztes Backoff mit Retry

Im Log mindestens Zeit, Statuscode, Geschäftscode, Modellname, Dauer und trace_id erfassen. Nie den vollständigen Key protokollieren und keine Nutzertexte im Ganzen ins Log schreiben.

2. 401 und 403: erst Authentifizierung, dann Rechte

401 bedeutet, dass die Identität nicht verifiziert wurde, und hat meist nichts mit den Modellfähigkeiten zu tun. Prüfen Sie in dieser Reihenfolge:

  • Ist der Header Authorization: Bearer <key> und keine eigene Authentifizierungsart?
  • Enthält der Key Leerzeichen, Zeilenumbrüche oder Anführungszeichen? Beim Kopieren aus Chatfenstern passiert das besonders leicht.
  • Wird die Umgebungsvariable tatsächlich geladen? Ein Ausdruck der ersten Zeichen schafft Klarheit.
  • Wurde der Key gelöscht, rotiert oder deaktiviert?
  • Gehören Base URL und Key zur selben Plattform? Ein offizieller Key an einer Gateway-Adresse führt zu 401.
  • Überschreibt oder verwirft ein Reverse-Proxy den Authorization-Header?
  • Werden M-Plan-Abonnement-Keys und nutzungsbasierte Keys vermischt? Laut offizieller Dokumentation sind beide getrennt, Kontingente sind nicht austauschbar.

403 deutet eher auf Rechte oder Kontostatus: Ist das Modell freigeschaltet, ist das Konto verifiziert, erlaubt der aktuelle Zugang dieses Modell, gibt es Gateway-Kontingent- oder Risikogrenzen? Die Semantik von 403 kann je nach Zugang abweichen; prüfen Sie zuerst Fehlermeldung und Herkunftsmarkierung im Antwortkörper. Wenn dieselbe Anfrage am offiziellen Zugang funktioniert und am Gateway 403 liefert, prüfen Sie Gateway-Konfiguration und Kontingent.

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

404 heißt meist nicht „die Schnittstelle ist ausgefallen“, sondern die Anfrage traf einen nicht existierenden Pfad oder ein nicht existierendes Modell. Häufige Ursachen:

  • Die Base URL gehört zu einem anderen Anbieter, oder /v1 fehlt bzw. ist doppelt.
  • Das SDK hängt /chat/completions automatisch an, während der manuell geschriebene Pfad es erneut anhängt.
  • Der Modellname nutzt eine abgekündigte Altversion oder weicht in Groß-/Kleinschreibung oder Suffix ab.
  • Offizielle Adresse und Gateway-Adresse werden gemischt, obwohl die Pfadregeln differieren.
  • Rewrite-Regeln des Reverse-Proxy verändern den Pfad.

Die offizielle Modellliste von MiniMax zeigt, dass historische Textmodelle wie M2.5/M2.7 im Abschaltprozess sind: Für neue Nutzer endet der Dienst am 19. Oktober 2026, die vollständige Abschaltung ist für den 18. November 2026 geplant. Aktuell dokumentiert sind MiniMax-M3 und MiniMax-M3.1-Flash. Wer alte Modellnamen weiterverwendet, riskiert 404 oder Geschäftsfehler. Prüfen Sie vor einer Migration Modellnamen in der offiziellen Liste und auf unserer Preisseite.

4. 429: Rate-Limit ist kein leeres Guthaben

429 bedeutet, dass die Anfrage eine Rate-, Parallelitäts- oder Kontingentgrenze überschritten hat. Die offizielle Rate-Limit-Dokumentation begrenzt über RPM (Anfragen pro Minute), TPM (Input plus Output pro Minute) und parallele Aufgaben; Haupt- und Unterkonten teilen sich das Kontingent. Für M3/M3.1-Flash nennt die Dokumentation aktuell als Standard: kostenlose Nutzer 20 RPM, aufgeladene Nutzer 200 RPM, TPM jeweils 1 Million bzw. 10 Millionen. Maßgeblich ist die Konsole.

Häufige Auslöser:

  • Mehrere Dienste teilen einen Key und verdrängen sich gegenseitig.
  • Batch-Aufgaben starten zur vollen Stunde gleichzeitig und erzeugen eine Verkehrsspitze.
  • Retries ohne Backoff erzeugen einen Retry-Sturm.
  • Lange Ausgaben oder Reasoning-Aufgaben belegen Ressourcen und verengen die Parallelität.
  • Das Tariffenster endet und die Ressourcengrenze des M Plan greift.

Gegenmaßnahmen: Keys je Projekt trennen; Batch-Aufgaben über eine Warteschlange glätten; Retries mit Obergrenze, exponentiellem Backoff und Jitter versehen; lange Ausgaben separat drosseln; Retry-After im Antwortheader bevorzugt befolgen. Bei 429 nicht weiter Parallelität erhöhen, sondern zuerst den Anfragefluss glätten.

5. Timeouts und 5xx: Verbindung, erstes Token und Lesen trennen

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

  • Verbindungs-Timeout: DNS, Netzausgang oder Proxy nicht erreichbar; Netz und Proxy prüfen.
  • Langsames erstes Token: Upstream-Warteschlange oder zu langer Prompt; Eingabe kürzen, Nebenzeit nutzen oder ein leichteres Modell wählen.
  • Lese-Timeout: Ausgabe zu lang oder Reasoning-Modell denkt lange; Lese-Timeout erhöhen und Ausgabe begrenzen.
  • Streaming-Abbruch: Netzschwankung oder Proxy-Abbruch; der Client muss Wiederverbindung und Deduplizierung beherrschen.
  • Timeout asynchroner Aufgaben: Bei Video und Sprache zwischen „Aufgabe in Warteschlange“ und „Anfrage-Timeout“ unterscheiden, per task_id abfragen und nicht doppelt einreichen.

5xx und die Geschäftscodes 1000, 1024, 1033 deuten meist auf Upstream-Störungen oder Überlast. Solche Fehler eignen sich für begrenztes Backoff. Bei Anfragen mit Nebenwirkungen vorher per Idempotenzschlüssel oder Statusabfrage klären, ob sie ausgeführt wurden. Download-Links für asynchrone Sprachausgaben haben eine Gültigkeit (laut offizieller Angabe derzeit 9 Stunden) und müssen danach neu angefordert werden.

6. Fehlerbehandlungscode: Backoff, trace_id und Logging

import logging
import os
import random
import time

import httpx
from openai import (
    APITimeoutError,
    APIStatusError,
    AuthenticationError,
    OpenAI,
    RateLimitError,
)

log = logging.getLogger("minimax")
client = OpenAI(
    api_key=os.environ["MINIMAX_API_KEY"],
    base_url=os.environ.get("MINIMAX_BASE_URL", "https://api.minimax.cn/v1"),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # automatische SDK-Retries aus, Steuerung erfolgt unten
)

def trace_id(exc: Exception) -> str:
    response = getattr(exc, "response", None)
    headers = getattr(response, "headers", {}) or {}
    return headers.get("trace_id") or headers.get("x-request-id") or "-"

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["MINIMAX_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            log.error("Authentifizierung fehlgeschlagen status=%s trace_id=%s", exc.status_code, trace_id(exc))
            raise
        except RateLimitError as exc:
            wait = min(2 ** attempt, 30) + random.uniform(0, 1)
            log.warning("Rate-Limit ausgeloest attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APITimeoutError as exc:
            wait = min(2 ** attempt, 15) + random.uniform(0, 1)
            log.warning("Timeout attempt=%s wait=%.1fs trace_id=%s",
                        attempt + 1, wait, trace_id(exc))
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 30) + random.uniform(0, 1)
                log.warning("Upstream-Fehler status=%s attempt=%s wait=%.1fs trace_id=%s",
                            exc.status_code, attempt + 1, wait, trace_id(exc))
                time.sleep(wait)
                continue
            log.error("Client-Fehler status=%s detail=%s trace_id=%s",
                      exc.status_code, exc, trace_id(exc))
            raise
    raise RuntimeError("Retries erschoepft, bitte mit trace_id an den Anbieter wenden")

print(ask("Erklaeren Sie API-Rate-Limits in einem Satz"))

Der Code leistet vier Dinge: wiederholbare und nicht wiederholbare Fehler trennen, exponentielles Backoff mit Jitter, trace_id ins Log schreiben und 5xx separat behandeln. Er ersetzt kein Idempotenzdesign; Anfragen mit Nebenwirkungen erfordern weiterhin eine Statusprüfung.

7. Logging und Monitoring: die minimalen Felder

  • Zeit und Projekt: Spitzen und Auswirkungen eingrenzen.
  • HTTP-Statuscode und Geschäftscode: Authentifizierung, Rate-Limit, Parameter und Upstream unterscheiden.
  • trace_id oder x-request-id: entscheidender Beleg für die Fehlersuche beim Anbieter.
  • Schnittstellenadresse und Modellname: erkennen, ob ein Wechsel von Modell oder Zugang die Ursache ist.
  • Input- und Output-Token: Kosten und lange Anfragen analysieren.
  • Dauer, Retry-Anzahl und Parallelität: Tail-Latenz und Retry-Stürme erkennen.
  • Key-Alias: projektweise auswerten, niemals den Key im Klartext protokollieren.

Das Monitoring sollte mindestens stündlich 401, 403, 404, 429, Timeouts und 5xx zählen. Steigt die Fehlerrate sprunghaft, zuerst prüfen, ob sie sich auf ein Projekt, einen Key oder ein Modell konzentriert, und dann Parallelität senken, Kanal wechseln oder Version zurückrollen.

8. Checkliste vor der Support-Anfrage

  1. Zeitpunkt, Zeitzone, Dauer und betroffene Schnittstellen.
  2. HTTP-Statuscode, Geschäftscode und vollständige Fehlermeldung, Sensibles vorher anonymisieren.
  3. trace_id aus dem Antwortheader sowie eine eventuell vom Gateway ergänzte x-request-id.
  4. Schnittstellenadresse, Modellname, SDK-Version und Anfrageparameter.
  5. Ein reproduzierbares Minimal-curl ohne Geschäftsdaten und personenbezogene Informationen.
  6. Offizielle Direktverbindung oder Gateway, nutzungsbasierter Key oder M-Plan-Key.
  7. Gleichzeitige Parallelität, RPM/TPM, Retry-Anzahl und mögliche Verkehrsspitzen.
  8. Wurden kürzlich Modell, SDK, Proxy oder Gateway-Konfiguration geändert?
  9. Bei 1008 einen Screenshot des Guthaben- oder Tarifstatus beilegen, ebenfalls anonymisiert.

Alles in einer Nachricht gebündelt beschleunigt die Bearbeitung erheblich gegenüber einem bloßen „es gibt einen Fehler“. Anbieter brauchen meist zuerst trace_id und Zeitfenster.

Häufige Fragen

Ist 429 ein leeres Guthaben?

Nein. 429 bedeutet, dass eine Rate-, Parallelitäts- oder Kontingentgrenze überschritten wurde; für unzureichendes Guthaben steht üblicherweise der Geschäftscode 1008. Prüfen Sie zuerst Parallelität, geteilte Keys und Verkehrsspitzen.

Warum meldet HTTP 200 dennoch einen Fehler?

Einige native MiniMax-Schnittstellen drücken Geschäftsfehler über base_resp.status_code im Antwortkörper aus, während die HTTP-Ebene 200 bleibt. Bei solchen Schnittstellen darf der Code nicht nur den HTTP-Status prüfen, sondern muss den Antwortkörper auswerten; OpenAI-kompatible Zugänge liefern üblicherweise direkt HTTP-Fehlercodes.

Woher bekommt man die trace_id?

Die offizielle Fehlercode-Dokumentation verweist auf die trace_id im Antwortheader. Über ein Gateway kann zusätzlich eine x-request-id zurückkommen; beide protokollieren.

Kann man Timeouts unbegrenzt wiederholen?

Nein. Retries brauchen Obergrenze, Backoff und Alarmierung; ein Timeout kann bedeuten, dass die Anfrage upstream bereits läuft. Bei Anfragen mit Nebenwirkungen zuerst den Status prüfen und dann über eine erneute Sendung entscheiden.

Was tun bei 404 nach einem Modellwechsel?

Zuerst prüfen, ob der Modellname abgekündigt ist, dann, ob die Base URL /v1 zu viel oder zu wenig enthält. Die historischen Textmodelle von MiniMax werden schrittweise abgeschaltet; alte Namen dürfen nicht mehr als verfügbar vorausgesetzt werden. Maßgeblich sind die offizielle Modellliste und unsere Preisseite.

Nächste Schritte

Erstellen Sie zunächst einen Test-Key im ZSQH AI Gateway, spielen Sie 401, 404, 429 und einen Timeout je einmal durch und binden Sie dann das Produktionsmonitoring an. Modellverfügbarkeit und Preise richten sich nach den Modellpreisen.

Verwandte Artikel: