Die meisten Fehler der Mistral API sind keine Frage der Modellfähigkeit, sondern von Zugangsdaten, Pfad, Parametern, Rate-Limits oder Netzwerk. Die Reihenfolge der Fehlersuche sollte lauten: zuerst HTTP-Statuscode und Fehlertyp prüfen, dann Request-ID und minimale Reproduktion in der Antwort, und erst danach Prompt oder Modell ändern. Wer die Reihenfolge umdreht, verwechselt leicht einen Konfigurationsfehler mit einem schwachen Modell.

Dieser Beitrag geht 401, 403, 404, 422, 429, 5xx und Timeouts einzeln durch und liefert Retry-Code, Nebenläufigkeitskontrolle, Log-Felder und eine Checkliste für Support-Tickets. Konkrete Kontingente, Fehlertexte und Schnittstellenverhalten richten sich nach der offiziellen Mistral-Dokumentation und der Konsole.

Hinweis: Mistral ist eine Marke des jeweiligen Inhabers. Dieser Beitrag dient der technischen Diskussion. Fehlercodes, Limitregeln und Schnittstellenverhalten können sich mit Versionen ändern; maßgeblich sind die offizielle Dokumentation und die Konsole.

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

Status oder Symptom Häufige Bedeutung Typische Ursache Reihenfolge der Behandlung
401 Authentifizierung fehlgeschlagen Schlüssel fehlt, falsch formatiert oder ungültig Zuerst Zugangsdaten prüfen
403 Keine Berechtigung Modell nicht freigeschaltet, Workspace-Rolle zu gering, Regionsbeschränkung Konto und Rechte prüfen
404 Pfad oder Modell existiert nicht Falsche Base URL, doppelter Pfad, Modell abgekündigt Adresse und Modellnamen prüfen
422 Anfrage semantisch ungültig Feld fehlt, falscher Typ, Parameter nicht unterstützt Fehlerdetails lesen und Parameter ändern
429 Rate-Limit oder Kontingent erreicht Plötzliche Parallelität, geteilter Schlüssel, Retry-Sturm Backoff, Parallelität senken
5xx Fehler des Upstream-Dienstes Überlastung, Gateway-Fehler, temporäre Störung Begrenzt wiederholen, Zugang wechseln
Timeout Verbindungs- oder Lese-Timeout Netzwerkstörung, zu lange Ausgabe, Leerlauf-Timeout des Proxys Schichtweise eingrenzen

Im Log sollten mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname, Dauer und Request-ID stehen. Vollständige Schlüssel und Nutzertexte gehören nicht ins Log.

2. 401 und 403: Authentifizierung und Berechtigung

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

  • Enthält der Header Authorization: Bearer <key> und nicht ein eigenes Feld oder eine alte Authentifizierungsform?
  • Stehen vor oder nach dem Schlüssel Leerzeichen, Zeilenumbrüche oder zusätzliche Anführungszeichen? Beim Kopieren aus Chatfenstern passiert das besonders häufig.
  • Wird die Umgebungsvariable tatsächlich geladen? Zur Kontrolle nur das Präfix ausgeben, niemals den vollständigen Schlüssel.
  • Wurde der Schlüssel gelöscht, rotiert oder deaktiviert? Wird in der Testumgebung versehentlich ein Produktionsschlüssel verwendet?
  • Gehören Base URL und Schlüssel zur selben Plattform? Ein Schlüssel von Plattform A an der Adresse von Plattform B führt direkt zu 401.
  • Überschreibt oder verwirft ein Reverse-Proxy oder das SDK den Authorization-Header?

403 bedeutet „Identität erkannt, aber keine Berechtigung“. Häufige Ursachen: Das aktuelle Konto oder der Workspace darf das Modell nicht aufrufen, die Rolle reicht nicht aus, das Modell ist in der Region nicht freigeschaltet, oder die Anfrage trifft eine nicht aktivierte Schnittstelle. Prüfen Sie zuerst Modellliste und Mitgliederrechte in der Konsole und rufen Sie anschließend mit demselben Schlüssel ein nachweislich verfügbares Modell als Vergleich auf.

3. 404 und 422: Adresse, Modellname und Parameter

404 heißt meist nicht, dass die Schnittstelle ausgefallen ist, sondern dass die Anfrage einen nicht existierenden Pfad oder ein nicht existierendes Modell trifft. Typische Ursachen sind eine falsche Base URL, ein zusätzliches oder fehlendes /v1, eine doppelte Pfadzusammensetzung durch SDK und handgeschriebenen Code, ein abgekündigter alter Modellname oder eine fehlende Route im Gateway. Senden Sie zuerst eine minimale Anfrage an die vollständige Adresse, prüfen Sie die Fehlermeldung im Antwortkörper und vergleichen Sie dann die Modellliste der Konsole.

422 bedeutet, dass die Anfrage formal korrekt, aber semantisch ungültig ist. Häufig fehlen Pflichtfelder, ein Feldtyp ist falsch, messages ist leer, max_tokens liegt außerhalb des Bereichs, ein vom aktuellen Modell nicht unterstützter Parameter wurde übergeben, oder die JSON-Struktur ist beschädigt. Der Antwortkörper nennt in der Regel Feldposition und Grund. Lesen Sie zuerst detail oder error und ändern Sie gezielt, statt blind zu wiederholen.

4. 429: Rate-Limits, Parallelität und Retry-Stürme

429 zeigt an, dass die Anfrage ein Rate-, Parallelitäts- oder Kontingentlimit überschritten hat, und bedeutet nicht automatisch fehlendes Guthaben. Häufige Auslöser:

  • Mehrere Dienste teilen einen Schlüssel und verdrängen sich gegenseitig.
  • Batch-Aufgaben starten alle zur vollen Stunde und erzeugen einen Verkehrsimpuls.
  • Wiederholungen ohne Backoff verstärken sich selbst zu einem Retry-Sturm.
  • Lange Ausgaben oder Streaming-Anfragen belegen Verbindungen länger und lassen weniger Parallelität übrig.
  • Test-, Vorab- und Produktionsumgebung sind nicht getrennt, und Testverkehr verbraucht das Produktionskontingent.

Prüfen Sie zuerst, ob die Antwort Retry-After oder einen ähnlichen Hinweis enthält, und warten Sie entsprechend. Fehlt der Hinweis, verwenden Sie exponentielles Backoff mit zufälligem Jitter. Senken Sie gleichzeitig die Parallelität, geben Sie Batch-Aufgaben eine Warteschlange und einen Token-Bucket und setzen Sie Limits pro Modell, pro Schlüssel und pro Umgebung. Wiederholungen sind kein Kapazitätsausbau: Sie fangen kurze Schwankungen ab, lösen aber keinen dauerhaften Kapazitätsmangel.

5. 5xx und Timeouts: Upstream, Netzwerk und Streaming

Zu 5xx zählen 500, 502, 503 und 504. Ursachen können Überlastung des Upstream-Dienstes, fehlgeschlagene Gateway-Weiterleitung oder temporäre Störungen sein. Klären Sie zuerst den Umfang: Scheitern alle Modelle, oder nur ein Modell, eine Region oder eine bestimmte Strecke? Kurze 5xx-Phasen lassen sich begrenzt wiederholen; bei anhaltenden 5xx sollte die Parallelität gesenkt, ein Ersatzzugang genutzt und die Request-ID für die Unterstützung beim Plattformbetreiber aufbewahrt werden.

Timeouts sind nach Verbindungs-Timeout, Lese-Timeout und Leerlauf-Timeout beim Streaming zu unterscheiden. Verbindungs-Timeouts hängen meist mit Netzwerk, DNS oder Proxy zusammen. Lese-Timeouts treten bei langen Ausgaben, komplexem Reasoning und Warteschlangen im Upstream auf. Bei Streaming kann zusätzlich der Leerlauf-Timeout eines Proxys die Verbindung trennen. Der Client sollte Verbindungs- und Lese-Timeout ausdrücklich setzen; für Streaming sind Leerlauf-Timeout und Wiederverbindungsstrategie nötig. Anfragen mit Nebenwirkungen sollten nach einem Timeout nicht sofort erneut gesendet werden, bevor geklärt ist, ob der Upstream sie bereits ausgeführt hat.

6. Request-ID und Logs: die Grundlage der Fehlersuche

Die Request-ID verbindet Teams bei der gemeinsamen Analyse. Sie steht meist im Antwortheader oder im Fehlerkörper, häufig als x-request-id. Ob direkt oder über ein Gateway: Die ID gehört ins Log und sollte mit der internen Vorgangsnummer verknüpft werden.

Ein gutes Log enthält mindestens Zeitpunkt, Request-ID, Statuscode, Fehlertyp, Modellname, Anzahl der Input- und Output-Token, Dauer, Anzahl der Wiederholungen, Streaming ja/nein und den Upstream-Zugang. Nutzerinhalte werden anonymisiert oder nur als Zusammenfassung gespeichert; vom Schlüssel wird ausschließlich das Präfix protokolliert. Ein Fehler-Screenshot ohne Request-ID macht es dem Support schwer, die konkrete Anfrage zu finden.

7. Retry und Backoff: was wiederholbar ist und wie

Eine Wiederholung braucht drei Voraussetzungen: behebbarer Fehler, wiederholbare Anfrage und eine Obergrenze. 401, 403, 404 und 422 sollten nicht wiederholt werden; sie weisen auf Konfiguration oder Parameter hin, und Wiederholungen kosten nur Zeit. 429, 5xx und Timeouts dürfen begrenzt wiederholt werden, wobei Retry-After Vorrang hat.

Das folgende Beispiel kombiniert wiederholbare Statuscodes, exponentielles Backoff, zufälligen Jitter und die Request-ID. In der Produktion kommen Circuit Breaker, Metriken und eine Prüfung der fachlichen Idempotenz hinzu.

import os
import random
import time

import requests

API_KEY = os.environ["MISTRAL_API_KEY"]
URL = "https://api.mistral.ai/v1/chat/completions"
RETRY_STATUS = {429, 500, 502, 503, 504}


def wait_seconds(resp, attempt):
    value = resp.headers.get("Retry-After") if resp is not None else None
    if value:
        try:
            return min(float(value), 60.0)
        except ValueError:
            pass
    return min(2 ** attempt + random.random(), 30.0)


def chat(payload, max_retries=4):
    last_error = None
    for attempt in range(max_retries + 1):
        try:
            resp = requests.post(
                URL,
                headers={
                    "Authorization": f"Bearer {API_KEY}",
                    "Content-Type": "application/json",
                },
                json=payload,
                timeout=(5, 60),  # 5 Sekunden Verbindung, 60 Sekunden Lesen
            )
        except requests.Timeout as exc:
            last_error = exc
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(None, attempt))
            continue

        request_id = resp.headers.get("x-request-id", "unknown")
        if resp.status_code == 200:
            return resp.json()

        if resp.status_code in RETRY_STATUS:
            last_error = RuntimeError(
                f"HTTP {resp.status_code}, request_id={request_id}"
            )
            if attempt == max_retries:
                break
            time.sleep(wait_seconds(resp, attempt))
            continue

        # 401/403/404/422: Wiederholung ist sinnlos, Konfigurations- oder Parameterfehler offenlegen
        raise RuntimeError(
            f"HTTP {resp.status_code}, request_id={request_id}, "
            f"body={resp.text[:500]}"
        )

    raise RuntimeError(f"retry exhausted: {last_error}")

Neben Wiederholungen braucht es Nebenläufigkeitskontrolle: ein Semaphor pro Modell, eine Warteschlange für Batch-Aufgaben, getrennte Schlüssel pro Umgebung und Alarme auf den 429-Anteil. Rate-Limits sind ein Kapazitätsthema, kein gelegentlicher Ausnahmefall.

8. Checkliste für das Support-Ticket

Vor der Kontaktaufnahme mit dem Support sollten die folgenden Angaben gesammelt werden; das verkürzt die Analyse deutlich:

  1. Zeitpunkt und Zeitraum mit Zeitzone sowie Angabe, ob der Fehler dauerhaft oder sporadisch auftritt.
  2. Vollständige Request-ID, zugehöriger Statuscode und Fehlerkörper, in anonymisierter Form.
  3. Anfrageadresse, Modellname, Streaming ja/nein, Nutzung von Tool-Aufrufen oder strukturierter Ausgabe.
  4. Eine minimale reproduzierbare Anfrage ohne geschäftsfremde Felder, aber mit allen notwendigen Parametern.
  5. Auswirkungsbereich: wie viele Nutzer, welche Regionen und Netzwerke betroffen sind und ob alle Modelle scheitern.
  6. Letzte Änderungen: Schlüsselrotation, Modell-Upgrade, Anpassungen an Proxy oder Gateway.
  7. Bereits durchgeführte Prüfungen und Ergebnisse, etwa Wechsel von Schlüssel, Modell, Netzwerk und reduzierter Parallelität.

Häufige Fragen

Warum schlägt 401 auch mit einem neuen Schlüssel fehl?

Prüfen Sie zuerst, ob der neue Schlüssel zur Plattform der aktuellen Base URL gehört, dann, ob die Umgebungsvariable wirklich geladen wird und ob der Proxy den Authorization-Header weitergibt. Minimale Anfragen an den offiziellen Zugang und an das Gateway zeigen schnell, ob der Schlüssel oder die Strecke das Problem ist.

Bedeutet 429, dass das Guthaben nicht reicht?

Nein. 429 zeigt eine Überschreitung von Rate-, Parallelitäts- oder Kontingentlimit an. Fehlendes Guthaben äußert sich meist in einem anderen Fehler oder wird im Antwortkörper genannt. Prüfen Sie zuerst Parallelität, geteilte Schlüssel und Retry-Strategie, danach den Kontostatus.

Worin unterscheiden sich 422 und 400?

Beide können Parameterprobleme anzeigen, doch 422 betont eine formal korrekte, semantisch ungültige Anfrage, etwa einen falschen Feldtyp oder ein fehlendes Pflichtfeld. In der Praxis richten sich beide nach den Feldhinweisen im Antwortkörper, nicht nach Vermutungen anhand des Statuscodes.

Darf nach einem Timeout sofort erneut gesendet werden?

Das hängt von den Nebenwirkungen der Anfrage ab. Reine Abfragen lassen sich begrenzt wiederholen. Bei Bestellungen, Zahlungen oder Nachrichtenversand muss zuerst geprüft werden, ob der Upstream bereits ausgeführt hat; alternativ sorgen Idempotenzschlüssel für Duplikatschutz. Ein Timeout bedeutet nur, dass der Client kein Ergebnis erhalten hat, nicht dass der Upstream nichts getan hat.

Was gehört in ein Support-Ticket?

Zeitraum, Request-ID, Statuscode, Fehlerkörper, Modellname, minimale Reproduktion und Auswirkungsbereich. Ergänzen Sie letzte Änderungen und bereits durchgeführte Prüfungen, damit der Support die konkrete Strecke schnell eingrenzen kann.

Nächster Schritt

Erstellen Sie zuerst im ZSQH AI Gateway einen Testschlüssel und üben Sie 401, 422, 429 und einen Timeout je einmal durch, bevor die Produktionsüberwachung angebunden wird. Verfügbarkeit der Modelle und Abrechnungsregeln enthält die Preisübersicht.

Weiterlesen: