Fehler der DeepSeek API lassen sich grob in vier Gruppen teilen: Authentifizierung, Pfad und Modellname, Drosselung und Timeouts. Die richtige Reihenfolge lautet: zuerst HTTP-Statuscode und Fehlertyp prüfen, dann Request-ID und minimale Reproduktion, erst danach Prompt oder Modell ändern. Wer die Reihenfolge umdreht, hält ein Konfigurationsproblem leicht für eine Modellschwäche.

Dieser Artikel trennt die vier Gruppen 401, 404, 429 und Timeout, nennt Ursachen, Prüfschritte und wiederverwendbaren Backoff-Code. Modelle und Preise stehen in den Modellpreisen.

Hinweis: DeepSeek ist eine Marke ihres jeweiligen Inhabers. Fehlertypen, Drosselungsregeln und Schnittstellenverhalten können sich mit Versionen ändern. Der Beitrag beschreibt die übliche Situation im Oktober 2026; maßgeblich ist die offizielle Dokumentation.

1. Zuerst die vier Fehlerklassen unterscheiden

Status oder Symptom Bedeutung Typische Ursache Reihenfolge
401 Authentifizierung fehlgeschlagen Falscher Key, fehlendes Bearer, abgelaufener Key Zuerst Zugangsdaten prüfen
404 Pfad oder Modell existiert nicht Falsche Base URL, veralteter Modellname, doppelter Pfad Adresse und Modellname prüfen
429 Drosselung oder Kontingent Plötzliche Parallelität, gemeinsamer Key, Retry-Lawine Backoff, Parallelität senken
Timeout Verbindungs- oder Lese-Timeout Netz, lange Ausgabe, Reasoning-Modell, Proxy Schichtweise prüfen
400 Parameter oder Kontext fehlerhaft Kontext zu lang, Formatfehler Nach Quantifizierung aufteilen
5xx Fehler des Upstream-Dienstes Serverstörung oder Überlast Backoff, Kanal wechseln

Im Log sollten mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname, Laufzeit und Request-ID stehen. Den vollständigen Key nie protokollieren und auch keine ganzen Nutzertexte ins Log schreiben.

2. 401: zuerst Header, dann Key

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

  1. Ob der Header Authorization: Bearer <key> verwendet und nicht eine andere Authentifizierungsart.
  2. Ob vor oder nach dem Key Leerzeichen, Zeilenumbrüche oder zusätzliche Anführungszeichen stehen. Beim Kopieren aus einem Chatfenster passiert das besonders häufig.
  3. Ob die Umgebungsvariable tatsächlich geladen ist; zum Prüfen nur das Präfix ausgeben.
  4. Ob der Key gelöscht, rotiert oder deaktiviert wurde.
  5. Ob Base URL und Key zur selben Plattform gehören; ein offizieller Key mit Gateway-Adresse führt zu 401.
  6. Ob ein Reverse Proxy den Authorization-Header überschreibt oder verwirft.
export DEEPSEEK_API_KEY="sk-IHR_KEY"

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

Antwortet dieser Befehl mit 200, stimmen Key, Base URL und Modellname. Kommt weiterhin 401, mit einem neuen Key eine minimale Anfrage senden, um zu unterscheiden, ob der Key selbst oder die Proxy- beziehungsweise Gateway-Konfiguration die Ursache ist.

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

404 bedeutet 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 beziehungsweise ist doppelt vorhanden.
  • Das SDK hängt /chat/completions automatisch an, während der Pfad manuell noch einmal angegeben wird.
  • Der Modellname stammt aus einer abgekündigten Version, oder Groß-/Kleinschreibung und Suffix weichen ab.
  • Gateway- und offizielle Adresse werden gemischt, obwohl die Pfadregeln unterschiedlich sind.
  • Rewrite-Regeln des Reverse Proxy beschädigen den Pfad.

Prüfen Sie zuerst mit curl gegen die vollständige Adresse und lesen Sie die Fehlermeldung im Antwortkörper; vergleichen Sie danach Base URL und Modellnamen Punkt für Punkt mit der Preisseite. Adressen nicht mehrfach im Code hartkodieren, sondern je Umgebung konfigurieren, damit die Testadresse nicht in die Produktion gelangt.

4. 429: Drosselung ist nicht zu wenig Guthaben

429 bedeutet, dass Rate, Parallelität oder Kontingent überschritten wurden. DeepSeek kann zu Spitzenzeiten Anfragen drosseln oder in eine Warteschlange stellen; die genauen Regeln stehen in der offiziellen Dokumentation. Häufige Auslöser:

  • Mehrere Dienste teilen sich einen Key und konkurrieren um dasselbe Kontingent.
  • Batch-Aufgaben starten zur vollen Stunde gleichzeitig und erzeugen eine Verkehrsspitze.
  • Wiederholungen ohne Backoff verschärfen den Fehler und erzeugen eine Retry-Lawine.
  • Lange Ausgaben oder Reasoning-Aufgaben belegen viele Ressourcen und lassen weniger Spielraum für Parallelität.
Symptom Mögliche Ursache Behandlung
429 konzentriert zu Spitzenzeiten Upstream-Last oder Verkehrsspitze Queue, gleichmäßiger senden, zeitlich versetzen
429 bei einem Key für mehrere Dienste Gemeinsames Kontingent Keys nach Projekt trennen
Nach Wiederholungen schlimmer Retry ohne Backoff Exponentielles Backoff mit Zufallsanteil
Lange Anfragen zuerst 429 Hoher Ausgabe-Token-Verbrauch max_tokens oder Parallelität senken 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-IHR_KEY",
    base_url="https://api.deepseek.com",
    max_retries=0,  # automatische SDK-Wiederholung aus, damit sie sich nicht mit der eigenen addiert
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
                timeout=60,
            )
            return resp.choices[0].message.content
        except (RateLimitError, APITimeoutError):
            wait = min(2 ** attempt, 20) + random.random()
            print(f"Versuch {attempt + 1} fehlgeschlagen, warte {wait:.1f} Sekunden")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Maximale Zahl der Wiederholungen erreicht")

print(ask("Erkläre in einem Satz, was Rate Limiting ist"))

Wiederholungen eignen sich nur für vorübergehende Fehler. Bei Vorgängen mit Nebenwirkungen zuerst mit Idempotenzschlüssel oder Statusprüfung klären, ob sie bereits ausgeführt wurden, und erst dann über erneutes Senden entscheiden.

5. Timeout: Verbindung, Lesen und Streaming trennen

Ein Timeout bedeutet nicht, dass der Dienst nicht verfügbar ist. Zuerst muss klar sein, an welcher Stelle es hängt:

Symptom Mögliche Ursache Behandlung
Verbindungs-Timeout DNS, Netzausgang, Proxy nicht erreichbar Netz und Proxy prüfen, Leitung wechseln
Erstes Token sehr spät Upstream-Warteschlange, zu langer Prompt Eingabe kürzen, Spitzen vermeiden, leichtes Modell
Lese-Timeout Ausgabe zu lang, Reasoning dauert Lese-Timeout erhöhen, Ausgabe begrenzen
Streaming bricht ab Netzschwankung, Proxy trennt Wiederverbindung unterstützen, Empfangenes speichern
Ganzes System gleichzeitig betroffen Lokaler Ausgang oder Upstream-Störung Ersatzkanal, Statusseite prüfen 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-IHR_KEY",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

Verbindungs- und Lese-Timeout sollten getrennt gesetzt werden. Ein sehr großer Wert für alle Timeouts blockiert bei Störungen den Thread-Pool; ein zu kleiner Wert beendet normale lange Aufgaben. Die Konfiguration nach Aufgabentyp ist stabiler.

6. Eine Tabelle für die Prüfreihenfolge

  1. Statuscode, Fehlertyp, Request-ID, Modellname und Zeitpunkt erfassen.
  2. Bei 401 Key, Header, Umgebungsvariablen und Plattformzugehörigkeit prüfen.
  3. Bei 404 Base URL, Pfadzusammensetzung und Modellnamen prüfen.
  4. Bei 400 Parameter, Kontextlänge, Bild- oder Dateiformat prüfen.
  5. Bei 429 Parallelität, gemeinsame Keys, Retry-Strategie und Spitzenzeiten prüfen.
  6. Bei Timeouts DNS, Proxy, Ausgabelänge und Lese-Timeout prüfen.
  7. Bei 5xx zuerst mit Backoff wiederholen; bei anhaltenden Fehlern den Dienstleister unter Angabe der Request-ID kontaktieren.
  8. Nach jeder Störung Monitoring und Alarme ergänzen, statt auf Nutzerbeschwerden zu warten.

7. Monitoring und Logs

Feld Zweck
Zeitpunkt und Projekt Spitzen und Auswirkungsbereich eingrenzen
Statuscode und Fehlertyp Authentifizierung, Drosselung und Upstream-Fehler unterscheiden
Request-ID Wichtigster Beleg für die Fehlersuche beim Dienstleister
Modellname und Version Erkennen, ob der Fehler nach einem Modellwechsel auftrat
Eingabe- und Ausgabe-Token Kosten und lange Anfragen analysieren
Laufzeit und Wiederholungen Tail-Latenz und Retry-Lawinen erkennen

Das Monitoring sollte 401, 404, 429, Timeouts und 5xx mindestens stündlich zählen. Steigt die Fehlerquote sprunghaft, zuerst prüfen, ob sie sich auf ein Projekt, einen Key oder ein Modell konzentriert, und dann entscheiden, ob Parallelität gesenkt, der Kanal gewechselt oder eine Version zurückgerollt wird.

Häufige Fragen

Bedeutet 429 zu wenig Guthaben?

Nein. 429 zeigt an, dass Rate, Parallelität oder Kontingent überschritten wurden. Fehlendes Guthaben führt in der Regel zu einem anderen Fehler oder wird im Antwortkörper genannt. Zuerst Parallelität und gemeinsame Keys prüfen, dann den Kontostand.

Was ist die häufigste Ursache für 404?

Falsche Base URL, doppelt zusammengesetzte Pfade und veraltete Modellnamen. Mit curl gegen die vollständige Adresse testen und den Modellnamen mit der Preisseite abgleichen; meist ist die Ursache in wenigen Minuten gefunden.

Sollte man bei Timeouts unbegrenzt wiederholen?

Nein. Wiederholungen brauchen eine Obergrenze, Backoff und Alarme. Ein Timeout kann außerdem bedeuten, dass die Anfrage upstream bereits ausgeführt wird. Bei Vorgängen mit Nebenwirkungen zuerst den Status prüfen.

Was tun, wenn die Streaming-Ausgabe abbricht?

Zuerst den bereits empfangenen Inhalt und die Abbruchstelle speichern, dann zwischen Netzschwankung, Proxy-Abbruch und Upstream-Timeout unterscheiden. Der Client sollte Wiederverbindung und Deduplizierung unterstützen und keine halben Antworten als vollständiges Ergebnis speichern.

Wie unterscheidet man Gateway-Fehler von offiziellen Fehlern?

Request-ID und Fehlertyp aufbewahren und dieselbe Anfrage sowohl an den offiziellen Einstieg als auch an das Gateway senden. So lassen sich Key, Netz, Gateway-Konfiguration und Upstream-Dienst schnell trennen.

Nächster Schritt

Erstellen Sie zuerst im ZSQH AI Gateway einen Test-Key und spielen Sie 401, 404, 429 und einen Timeout je einmal durch, bevor Sie das Produktionsmonitoring anbinden. Verfügbarkeit und Preise der Modelle stehen in den Modellpreisen.

Weiterlesen: