DeepSeek API Fehler und Fehlerbehebung

Hier beginnen#

1. Notiere Client-Version, gewähltes Modell, Anfragepfad, HTTP-Status, Fehlermeldung und Zeitpunkt mit Zeitzone. Notiere eine zurückgegebene Anfrage-ID, falls vorhanden; sie ist nicht garantiert.
2. Prüfe Dein Tarif, Verbrauch und den Abrechnungsmodus des Schlüssels unter API-Schlüssel. Website-Anmeldung und Inferenz-API-Schlüssel sind unterschiedliche Zugangsdaten.
3. Teste die minimale Anfrage unten mit demselben Schlüssel und Netzwerk wie der fehlerhafte Client. Ein erfolgreicher Chat-Completions-Aufruf bestätigt allein weder Messages noch Responses oder erweiterte Client-Tools.
4. Lies Status und Meldung gemeinsam. Fehler können unterschiedlich verpackt sein; hilfreicher Text steht eventuell in error.message, error.code, detailoder in einer einfachen HTML-Proxy-Antwort.

Entferne Schlüssel, Authorization-Header, Cookies, privaten Code und Prompts vor dem Teilen. Sende keine vollständige Umgebungsausgabe und aktiviere keine ausführliche HTTP-Protokollierung mit einem echten Schlüssel.

Richtige Verbindungsdaten verwenden#

Bei SDKs gehört der endgültige Endpunkt nicht in die Basis-URL. Claude Code ergänzt /v1/messages; verwende den Ursprung ohne /v1. Der Website-Host deepseeksub.com ist nicht der Inferenz-API-Host. Der öffentliche Proxy stellt die oben genannten Pfade und /v1/modelsbereit; verlasse dich nicht auf unversionierte Pfade oder /v1/responses/compact.

Verwende deepseek-flash, deepseek-v4-prooder dessen Dienst-Alias deepseek-pro. Ein Tarif namens Pro wählt nicht automatisch das Pro-Modell. Ältere Schlüssel können auf Flash beschränkt sein; siehe Modelle und Kompatibilität.

Eine Diagnoseanfrage senden#

Setze CODING_PLAN_API_KEY sicher im Terminal des Befehls, wie beschrieben unter API-Schlüssel. Diese Shell-Beispiele nutzen macOS-/Linux-Syntax. Windows-Nutzer können das Python-Beispiel mit der PowerShell-Umgebungseinrichtung unter API-Schlüssel verwenden. API-Schnellstart.

Prüfe zuerst DNS, TLS und HTTP-Erreichbarkeit ohne Schlüssel oder Generierung:

curl --silent --show-error --connect-timeout 10 --max-time 20 \
  --output /dev/null --write-out 'HTTP %{http_code}\n' \
  https://api.example.invalid/v1/models

Eine Authentifizierungsablehnung, normalerweise 401, bestätigt eine HTTP-Antwort, nicht aber Schlüssel, Modell oder Upstream-Funktion. HTTP 000 ist cURLs Kennzeichnung für eine ausbleibende Antwort, kein Serverstatus. 502/503/504 bedeutet, dass eine HTTP-Komponente geantwortet hat, der Dienstpfad aber untersucht werden muss.

Sende danach eine kurze Textanfrage. Sie kann Kontingent oder API-Guthaben verbrauchen. Der Befehl wiederholt nicht automatisch. Die 90-Sekunden-Grenze ist ein Diagnosebudget, keine Latenzgarantie.

curl --silent --show-error --connect-timeout 10 --max-time 90 \
  --write-out '\nHTTP %{http_code}; total %{time_total}s\n' \
  https://api.example.invalid/v1/chat/completions \
  -H "Authorization: Bearer ${CODING_PLAN_API_KEY:?Set CODING_PLAN_API_KEY first}" \
  -H 'Content-Type: application/json' \
  --data '{"model":"deepseek-flash","messages":[{"role":"user","content":"Say hello briefly."}],"max_tokens":128,"stream":false}'

Der Befehl gibt Fehlerantworten aus. HTTP-Fehler führen nicht zwingend zu einem cURL-Exitcode ungleich null; lies den ausgegebenen Status. Bei aktiviertem Reasoning kann ein kleines Ausgabebudget schon vor dem finalen Antworttext verbraucht sein. Prüfe finish_reason und Verbrauch, bevor du leeren Text als Verbindungsfehler deutest.

Installiere für Python openai und httpxund setze dann explizite Zeitlimits; deaktiviere SDK-Wiederholungen während der Diagnose:

import os
import httpx
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CODING_PLAN_API_KEY"],
    base_url="https://api.example.invalid/v1",
    timeout=httpx.Timeout(90.0, connect=10.0),
    max_retries=0,
)
response = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Say hello briefly."}],
    max_tokens=128,
    stream=False,
)
print(response.choices[0].message.content)

Das Python-Lesezeitlimit begrenzt das Warten auf Netzwerkdaten, nicht unbedingt die Gesamtdauer eines Streams.

Status- und Meldungsreferenz#

Diese Meldungen stammen aus der zugrunde liegenden Gateway- und Abrechnungsimplementierung. Clients, Proxys und Upstream-Anbieter können sie anders verpacken oder weitere Fehler liefern. HTTP 502/504 und 422 unten beschreiben mögliche Zwischenstellen- oder Anbieterantworten, keine speziellen Abrechnungscodes.

Authentifizierung und Modellzugriff korrigieren#

1. Verwende einen unter API-Schlüssel erstellten Dienstschlüssel API-Schlüsselund keinen Clerk-Anmeldetoken oder offiziellen DeepSeek-/OpenAI-/Anthropic-Schlüssel.
2. Sende für die Diagnoseanfrage Authorization: Bearer <key>. Prüfe zusätzliche Leerzeichen, unveränderte Platzhalter und fehlende Umgebungsvariablen im tatsächlichen Client-Prozess.
3. Ersetze abgelaufene oder widerrufene Schlüssel und aktualisiere den Client. Starte Desktop-/IDE-Anwendungen nach Änderungen ihrer Zugangsdatenquelle neu; ein Shell-Export aktualisiert keine bereits laufende Anwendung.
4. Bei MODEL_DENIED oder anderen Modellberechtigungsfehlern prüfe erlaubte Modelle und teste Flash. Fehlt einem älteren Schlüssel der Pro-Zugriff, erstelle einen neuen mit den benötigten Modellen. Tausche einen gültigen Schlüssel nicht allein wegen 502 oder einer Zeitüberschreitung.
5. Bleibt der Zugang verweigert, sende dem Support bereinigte Fehlermeldung und Zeitpunkt, niemals den vollständigen Schlüssel.

Kontingent-, Guthaben- und Parallelitätsfehler beheben#

1. Lies die Meldung: PLAN_EXHAUSTED, RATE_LIMIT und CONCURRENCY_LIMIT erfordern unterschiedliche Maßnahmen.
2. Bei PLAN_EXHAUSTEDprüfe, ob ein berechtigter Tarif aktiv ist und die Anfrage nach verbrauchten und reservierten Tokens in beide geltenden Fenster passt. Prüfe Rücksetzzeiten unter Dein Tarif; der Fehler garantiert keine Rücksetzfelder oder einen Retry-After Header.
3. Kürze Eingabe und Ausgabebudget, wenn die Reservierung nicht passt. Pro verbraucht das 3,5-Fache des Flash-äquivalenten Kontingents. Offene oder unklare Anfragen können Reservierungen behalten; ein lokales Timeout beweist keine Freigabe.
4. Prüfe den Abrechnungsmodus. Nur Tarif greift nie auf Guthaben zurück. Nur API-Guthaben verwendet keinen Tarif. Automatisch kann bei aktivierter Guthabennutzung darauf zurückgreifen; unzureichendes Guthaben kann dann zu folgendem Fehler führen: INSUFFICIENT_BALANCE. Aktivierter Rückgriff erlaubt Guthabenverbrauch; entscheide bewusst.
5. Bei CONCURRENCY_LIMITstoppe parallele Agenten und warte auf laufende Aufgaben. Bei RATE_LIMITpausiere die Anfrageschleife und reduziere die Häufigkeit. Dauerhaft ungeklärte Reservierungen erfordern Support.
6. Beachte Retry-After falls vorhanden. Andernfalls verwende begrenzte Warteintervalle bei vorübergehenden Ratenlimits. Einige Sekunden Warten lösen kein ausgeschöpftes 5-Stunden- oder 7-Tage-Fenster.

Nicht unterstützte Anfragen und große Kontexte korrigieren#

1. Beginne mit der reinen Text-Diagnoseanfrage. Ergänze Streaming, Verlauf, Tools und Reasoning-Optionen einzeln.
2. Entferne store: true, previous_response_id, background, metadata und Anbieter-Routing-Überschreibungen aus direkten Anfragen. Sie gehören nicht zum aktuellen öffentlichen Vertrag. Sende Gesprächsverlauf, statt dich auf gespeicherte Responses zu verlassen.
3. Entferne anbieterseitig gehostete Tools wie type: web_search und Responses-Tools mit type: custom. Clientseitig ausgeführte JSON-Schema-Funktionstools sind etwas anderes: Eine Clientfunktion namens web_search wird nicht allein wegen ihres Namens abgelehnt.
4. Verwende bei abgelehnten Medien Text. Die aktuelle öffentliche Validierung weist Medieneingaben zurück; Upstream-Modellfähigkeiten heben diese Einschränkung nicht auf.
5. Beginne bei 413 oder Kontextlängenfehlern ein neues Gespräch mit kurzer Zusammenfassung, entferne große Dateien und ungenutzte Tool-Schemata und reduziere das Ausgabebudget. HTTP-Nachrichtengröße und Modellkontext sind getrennte Grenzen.
6. Beginne bei Fehlern durch ausschließlich verschlüsseltes oder redigiertes Thinking-Replay ein neues Gespräch. Die Brücke benötigt Klartext-Reasoning für unterstützte Wiedergabe; verwende kein anbieterspezifisch verschlüsseltes Reasoning anderer Dienste.

502 Bad Gateway beheben#

1. Sichere Status, Zeitpunkt und bereinigte Antwort. HTML-Fehler können vor einer JSON-API-Antwort aus einem Proxy kommen; dies ist nicht automatisch ein Schlüsselproblem.
2. Prüfe Dienststatus und Störungsmeldungen. Die Statusseite allein prüft keine einzelne Anfrage; führe den obigen Test ohne Schlüssel aus.
3. Liefert auch der Test 502, pausiere die Generierung und melde Host und Zeitpunkt. Gateway-Prozess, Upstream-Verbindung oder Zwischenstellen können beteiligt sein; die Ursache erfordert Dienstprotokolle.
4. Funktioniert die Erreichbarkeit, versuche eine kurze Anfrage ohne parallele Aufgaben. Scheitert nur ein Client, vergleiche URL und Proxyeinstellungen. Vergleiche, soweit erlaubt, ein alternatives Netzwerk zur Eingrenzung lokaler Proxy-/VPN-Probleme.
5. Wiederhole höchstens zweimal nach etwa 2 und 5 Sekunden mit zufälliger Streuung; stoppe danach und kontaktiere den Support. Prüfe vor erneutem Senden den Verbrauch, falls die erste Anfrage das Modell erreicht haben könnte; eine neue Anfrage kann erneut Kosten verursachen.

504 Gateway Timeout beheben#

1. Bestätige eine tatsächliche HTTP-504-Antwort. APITimeoutError, ReadTimeout, ETIMEDOUT oder cURL-Exitcode 28 ohne HTTP-Antwort sind dagegen Client-/Netzwerkzeitüberschreitungen.
2. Notiere vergangene Zeit und ob Stream-Daten ankamen. Gleich lange Fehlerzeiten deuten auf ein Zeitlimit hin, identifizieren aber nicht die verantwortliche Komponente.
3. Teste einen neuen kurzen Textprompt mit kleinerem Ausgabelimit und ohne parallele Agenten. Bei Erfolg ergänze Kontext und optionale Funktionen schrittweise.
4. Nutze bei langen Antworten Streaming, falls unterstützt. Es zeigt Fortschritt, beseitigt aber keine Upstream-Rechen- oder Proxy-Leerlaufzeitlimits.
5. Gibt zuerst der Client auf, passe sein dokumentiertes Lese-/Leerlaufzeitlimit innerhalb eines endlichen Budgets an. Ein höheres Client-Zeitlimit repariert kein vom Gateway erzeugtes HTTP 504.
6. Prüfe Verbrauch und reserviertes Kontingent, dann die begrenzte Wiederholungsregel unten. Anhaltende 504 bei kleinen Anfragen benötigen Support mit Zeitangaben.

Verbindungszeitüberschreitungen, DNS- und TLS-Fehler beheben#

1. Führe den Test ohne Schlüssel in derselben Umgebung wie den Client aus: Terminal, Container, Remote-Host oder IDE. Ein funktionierender Browser anderswo bestätigt diese Umgebung nicht.
2. Prüfe HTTP_PROXY, HTTPS_PROXY und ALL_PROXY lokal auf veraltetes Routing. Veröffentliche keine Proxy-URLs mit Zugangsdaten. Beachte vorgeschriebene Netzwerkeinstellungen, statt sie blind zu umgehen.
3. Behebe zuerst DNS-, Firewall- und Zertifikatsprobleme. Deaktiviere weder die TLS-Prüfung noch verwende curl -k als Lösung.
4. Treten Timeouts nur bei großen Anfragen auf, reduziere Kontext/Ausgabe und prüfe Verbindungs-, Lese- und Stream-Leerlaufeinstellungen getrennt.
5. Stoppe Wiederholungsschleifen und prüfe den Verbrauch. Ein Timeout oder Abbruch beweist weder gestoppte Upstream-Verarbeitung noch null Token-Verbrauch oder eine freigegebene Reservierung.

Claude-Code-CLI-Prüfliste#

1. Notiere claude --version. Setze ANTHROPIC_BASE_URL auf https://api.example.invalid und verwende deinen Dienstschlüssel als ANTHROPIC_AUTH_TOKEN. Prüfe widersprüchliche gespeicherte Zugangsdaten und Einstellungen lokal.
2. Setze ANTHROPIC_MODEL und die Standardmodellvariablen für Opus/Sonnet/Haiku und Unteragenten aus der Claude-Code-Anleitung auf das gewünschte Modell. Die Modellauswahl im Hintergrund kann scheitern, obwohl der Hauptchat funktioniert.
3. Starte die CLI in diesem Terminal neu und teste ein neues kurzes Gespräch. Ein direkter Messages-Test verwendet /v1/messagesein messages Array, ein positives max_tokens und anthropic-version: 2023-06-01.
4. Prüfe bei 404 ein doppeltes /v1 oder einen nicht unterstützten Hilfsendpunkt. Prüfe bei 400 Tools, Medien und Thinking-Daten anhand der obigen Schritte.
5. Funktioniert Chat Completions, aber Messages nicht, melde den Messages-Fehler separat. Protokollumwandlung bestätigt nicht jede Clientfunktion. Diese Shell-Anleitung gilt für die CLI; Desktop-/verwaltete Integrationen können andere Einstellungen nutzen.

Codex-Prüfliste#

1. Notiere codex --version. Sichere Konfiguration und Modellkatalog. Führe Änderungen zusammen; doppelte TOML-Tabellen können den Start vor jeder HTTP-Anfrage verhindern.
2. In ~/.codex/config.tomlmuss model_provider zur Anbietertabelle passen; setze dessen base_url auf https://api.example.invalid/v1 und wire_api auf responses. Verwende eine Dienst-Modell-ID und einen env_key mit dem Namen der Umgebungsvariable, die deinen Schlüssel enthält.
3. Starte in dieser Umgebung neu und teste eine neue Sitzung. Ein direkter /v1/responses Test verwendet input, max_output_tokens und store: false. Chat-Completions-Erfolg allein ist kein Codex-Test.
4. Bei gehosteter Suche, benutzerdefinierten Tools, gespeicherten Responses oder nicht unterstützten Feldern folge den passenden Schritten oben. Kann der Client keine unterstützten Anfragen erzeugen, notiere Version und Fehler für den Support; wiederholter Schlüsseltausch hilft nicht.
5. Notiere bei 404 während der Kompaktierung den Pfad. /v1/responses/compact wird vom aktuellen öffentlichen Proxy nicht bereitgestellt. Beginne eine neue Sitzung mit kurzer Zusammenfassung; prüfe Anbieter-/Modellfähigkeiten des installierten Clients vor Aktivierung externer Kompaktierung.
6. Prüfe bei hängenden Streams stream_idle_timeout_ms, request_max_retries und stream_max_retries in den Anbietereinstellungen. Deaktiviere automatische Wiederholungen während der Diagnose, soweit unterstützt. Behalte bestehende Modellmetadaten, statt die Kontextgröße anderer Anbieter zu kopieren.

OpenCode-Prüfliste#

1. Notiere opencode --version. In /connectwähle Other und verwende dieselbe Anbieter-ID wie in opencode.jsonzum Beispiel coding-plan.
2. Verwende npm: "@ai-sdk/openai-compatible", options.baseURL: "https://api.example.invalid/v1" und eine genaue Dienst-Modell-ID als Schlüssel unter models. Ein Anzeigename ist keine API-Modell-ID.
3. Führe gültiges JSON zusammen, starte bei Bedarf neu und wähle das Modell mit /models. Fehlt der Anbieter, prüfe Syntax und Speicherort, bevor du Zugangsdaten änderst.
4. Verbinde bei Authentifizierungsfehlern den Schlüssel erneut unter der passenden Anbieter-ID. Bei Endpunktfehlern verwende /v1 genau einmal und hänge Folgendes nicht an: /chat/completions auf baseURL.
5. Teste ein neues kurzes Gespräch, dann Tools und längeren Kontext. Folge bei 400 oder Stream-Abbrüchen den Anfrage-/Netzwerkschritten; notiere Anbieter und Modell für den Support.

Eine Antwort bricht mittendrin ab#

1. Prüfe das Abschlusssignal des Protokolls und Fehlerereignisse. HTTP 200 beim Stream-Start garantiert keine abgeschlossene Generierung.
2. Unterscheide ein Ausgabelimit (finish_reason: length oder ein unvollständiges Responses-Ergebnis) von einem getrennten Stream. Ein Budgetlimit erfordert bewusstes Fortsetzen oder ein größeres unterstütztes Budget; ein Abbruch erfordert Netzwerk-/Zeitlimitdiagnose.
3. Kennzeichne Teilausgaben als unvollständig. Hänge nicht stillschweigend eine neue Generierung an und wiederhole keine teilweise ausgeführten Tool-Aktionen. Prüfe vorher, ob ein Tool bereits Dateien geändert oder externe Aktionen ausgeführt hat.
4. Prüfe Verbrauch. Fehlende finale Verbrauchsdaten können eine offene oder unklare Reservierung zur Abstimmung zurücklassen. Fehlende Nutzungsdaten oder eine geschlossene Verbindung bedeuten nicht null Kosten.
5. Bewahre letzten Ereignistyp, vergangene Zeit und bereinigte Fehlermeldung auf. Siehe Streaming-Antworten.

Wiederholen ohne Endlosschleife#

Behebe ungültige Anfragen und Authentifizierungs-/Zugriffsfehler vor Wiederholungen. Beachte bei vorübergehendem 429-Ratenlimit oder 500/502/503/504 Retry-After falls vorhanden; sonst höchstens zwei Wiederholungen mit steigenden Wartezeiten und Streuung, danach stoppen. Bei ausgeschöpftem Kontingent muss zuerst Fenster oder Abrechnung geklärt werden. Anhaltende Modell-/Abrechnungskonfigurationsfehler erfordern Support.

Deaktiviere während der Diagnose überlappende Wiederholungen in SDK, Client und eigenem Skript. Anfragen mit Timeout können bereits ausgeführt worden sein; prüfe den Verbrauch und entscheide über erneutes Senden. Wiederholte Generierung ist eine neue potenziell kostenpflichtige Anfrage, keine garantierte Fortsetzung oder kostenlose Wiederholung.

Einen hilfreichen Supportbericht vorbereiten#

Verwende Hilfe & Kontakt und ergänze Folgendes ohne Geheimnisse oder private Inhalte:

Time and timezone:
Client / version / operating system:
API host and final path (no query secrets):
Model ID / streaming on or off:
HTTP status, or network exception / cURL exit code:
Sanitized error code and message:
Elapsed time / whether response data arrived:
Request ID (only if returned):
Key billing mode / plan reset / pending usage:
Does the no-key probe work? Does one short text request work?
Minimal request with key and private prompt removed:

Verbindungseinstellungen wurden am 6. November 2026 gegen die Projektimplementierung geprüft. Clienteinstellungen können sich je nach Version ändern. Referenzen: Claude-Code-Gateway-Konfiguration, Codex-Konfigurationsreferenz, Benutzerdefinierte OpenCode-Anbieterund cURL-Exitcodes.