Cursor API-Fehler: 401, 404, 429 und Verbindungsprobleme (2026)

Wenn in Cursor ein eigener API-Key und eine eigene Base URL eingetragen werden, konzentrieren sich die Fehler meist auf vier Ebenen: Zugangsdaten, Pfad, Ratenbegrenzung und Netzwerk. Viele wechseln beim ersten roten Hinweis das Modell und machen aus einem Konfigurationsproblem einen halben Arbeitstag. Die richtige Reihenfolge lautet: zuerst den Statuscode lesen, dann mit einer minimalen Anfrage reproduzieren und erst zuletzt Modell oder Prompt ändern.

Dieser Artikel trennt 401, 404, 429, Verbindungsfehler, Streaming-Abbrüche und Kontextüberschreitungen auf und liefert Diagnosebefehle, Logfelder sowie eine ausführbare Checkliste für den Support.

Hinweis: Cursor ist eine Marke von Anysphere, Inc. Cursor wird häufig aktualisiert; Einstellungsmenüs und Fehlertexte können sich ändern. Dieser Artikel beschreibt gängige Versionen vom Oktober 2026; maßgeblich sind Ihre installierte Version und die offizielle Dokumentation.

1. Reihenfolge der Diagnose: erst schichten, dann konfigurieren

Statuscode/Phänomen	Häufige Bedeutung	Zuerst prüfen	Erneut versuchen
401	Key fehlt, ist falsch, abgelaufen oder ohne Berechtigung	Key, Auth-Feld, Kontostatus	Nein
403	Key hat keine Modellberechtigung oder Teamrichtlinie blockiert	Modellrechte, Teameinstellungen	Nein
404	Falscher Pfad oder Modell existiert nicht	Base URL, Modell-ID	Nein
429	Anfragefrequenz, Parallelität oder Token-Kontingent überschritten	Verbrauch, geteilter Key, Retry-Strategie	Nach Backoff
400/413	Anfrageformat fehlerhaft oder Kontext zu lang	Kontext, Parameter, max_tokens	Nach Änderung
5xx	Serverfehler oder Gateway überlastet	Dienststatus, Request-ID	Nach Backoff
Verbindungsfehler	DNS, TLS, Proxy, Firewall	Netzwerkpfad	Nach Behebung

Fixieren Sie zuerst eine Variable: gleicher Key, gleiche Base URL, gleiche Modell-ID, und ändern Sie immer nur eine Sache. Wenn Sie drei Dinge gleichzeitig ändern, wissen Sie auch bei Erfolg nicht, welches den Ausschlag gab.

2. 401: zuerst den Key prüfen, dann das Auth-Feld

401 bedeutet, dass die Identität nicht verifiziert wurde; Modellfähigkeit und Kontextlänge spielen keine Rolle. Prüfen Sie in dieser Reihenfolge:

Wurde der Key vollständig kopiert, ohne Leerzeichen, Zeilenumbrüche oder Anführungszeichen davor und danach? Beim Kopieren aus einem Chatfenster schleichen sich besonders leicht unsichtbare Zeichen ein.
Steckt der Key im richtigen Provider-Feld? Cursor trennt OpenAI, Anthropic, Google, Azure und weitere; im falschen Feld führt auch ein gültiger Key zu 401.
Wurde der Key gelöscht, deaktiviert oder ist er abgelaufen? Prüfen Sie den Status in der Gateway-Konsole, nicht nur in einer lokalen Datei.
Hat das Konto ein verfügbares Guthaben oder Kontingent? Manche Gateways antworten bei zu niedrigem Guthaben mit 401 oder 403; der Fehlertext entscheidet.
Verbietet das Team persönliche Drittanbieter-Keys? Cursor Teams/Enterprise kann BYOK in der Verwaltung sperren; dann scheitert auch eine korrekte lokale Konfiguration.
Zeigt die Base URL auf die Umgebung, zu der der Key gehört? Ein Test-Key an der Produktionsadresse ergibt meist ebenfalls 401.
Wurden die Umgebungsvariablen tatsächlich geladen? Geben Sie nur die ersten und letzten vier Zeichen des Keys aus, niemals den vollständigen Key im Log.

# Minimaler Auth-Test: prüft nur Adresse, Key und Protokoll
export API_KEY="sk-IhrSchluessel"

curl -sS -o /tmp/cursor_resp.json -w "%{http_code}\n" \
  "https://api.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $API_KEY"

cat /tmp/cursor_resp.json

Eine 200 zeigt, dass Key und Adresse grundsätzlich funktionieren. Bei 401 testen Sie denselben Key im Testbereich der Gateway-Konsole und unterscheiden so, ob der Key selbst oder das Feld beziehungsweise die Netzwerkschicht von Cursor das Problem ist.

3. 404: Base URL und Modell-ID teilen sich die Ursache

Ein 404 heißt nicht zwingend, dass ein Modell abgeschaltet wurde. Die häufigste Ursache ist ein falsch zusammengesetzter Pfad:

Der Base URL fehlt /v1; die Anfrage landet auf einer Web-Route und liefert HTML oder 404.
Der Base URL enthält bereits /v1/chat/completions, und der Client hängt denselben Pfad erneut an: /v1/chat/completions/chat/completions.
Anthropics /v1/messages wurde in ein OpenAI-kompatibles Feld eingetragen oder umgekehrt.
Der Domainname ist falsch, oder die Konsolenadresse wurde für die API-Adresse gehalten.

Auch die Modell-ID kann 404 oder model_not_found auslösen:

Groß-/Kleinschreibung, Bindestriche und Versionsnummer müssen exakt mit der Preisseite oder Modellliste übereinstimmen.
Das Modell ist für das aktuelle Konto oder den Tarif möglicherweise nicht freigeschaltet.
Dasselbe Modell kann unter verschiedenen Protokollen unterschiedliche IDs haben.
Die Verify-Schaltfläche in Cursor prüft meist nur Key und Erreichbarkeit der Adresse, nicht die Modell-ID; ein echter Request ist nötig.

Rufen Sie zuerst /v1/models auf, sofern das Gateway diesen Endpunkt anbietet, und kopieren Sie die Modell-ID aus der Antwort. Tippen Sie sie nicht von Hand ab.

4. 429: Ratenbegrenzung ist nicht gleich fehlendes Guthaben

429 bedeutet, dass eine Anfrage die Rate, die Parallelität oder das Token-Kontingent überschritten hat. Typische Auslöser:

Anfragen pro Minute oder Token pro Minute sind überschritten.
Mehrere Personen teilen einen Key und verdrängen sich gegenseitig.
Ein Agent liest fortlaufend Dateien und führt Befehle aus, sodass in kurzer Zeit sehr viele Anfragen entstehen.
Retries erfolgen ohne Backoff; je häufiger es scheitert, desto mehr Anfragen werden gesendet, bis ein Retry-Sturm entsteht.
Lange Kontextanfragen verbrauchen viel Kontingent und lassen weniger Spielraum für Parallelität.

Sehen Sie sich zuerst Antwort-Header und Fehlerkörper an, statt blind zu verdoppeln. Existiert Retry-After, warten Sie entsprechend; sonst verwenden Sie exponentielles Backoff mit zufälligem Jitter. 401 und 404 sollten nicht wiederholt werden; ein Retry vergrößert das Problem nur.

import random
import time

def retry_delay(attempt, base=1.0, cap=30.0):
    delay = min(cap, base * (2 ** attempt))
    return delay + random.uniform(0, delay * 0.3)

for attempt in range(4):
    response = send_request()  # durch Ihre Anfragefunktion ersetzen
    if response.status_code not in (429, 500, 502, 503, 504):
        break
    time.sleep(retry_delay(attempt))

Treten 429 gehäuft in festen Zeitfenstern auf, arbeiten Sie mit Warteschlange und gleichmäßigem Versand. Nutzt ein Key mehrere Dienste, trennen Sie Keys nach Projekt. Läuft ein Agent in einer Schleife, setzen Sie maximale Runden und ein Kontingentlimit.

5. Verbindungsfehler: SSL, Proxy und DNS

Verbindungsfehler liefern oft keinen HTTP-Status, sondern Timeouts, ECONNRESET, Zertifikatsfehler oder „keine Verbindung zum Server“. Prüfreihenfolge:

Mit curl -Iv feststellen, an welcher Stelle DNS-Auflösung, TCP-Verbindung oder TLS-Handshake stehen bleiben.
Ist das Zertifikat abgelaufen, selbst signiert oder durch das Firmennetz ersetzt? Bei TLS-Inspektion durch einen Unternehmensproxy muss das Firmen-Root-Zertifikat in den Trust Store.
Gelten Proxy-Umgebungsvariablen nur im Terminal, während Cursor selbst keinen Proxy nutzt? Prüfen Sie die Netzwerk-/Proxy-Einstellungen von Cursor und vergleichen Sie Direktverbindung und Proxy.
Blockieren VPN, Firewall oder Sicherheitssoftware langlebige Verbindungen oder Streaming-Antworten?
Ist die Systemzeit korrekt? Eine große Zeitabweichung lässt die Zertifikatsprüfung scheitern.
Stören Zwischengeräte HTTP/2 oder Verbindungs-Reuse? Testen Sie zuerst eine kurze, nicht gestreamte Anfrage.

Verwenden Sie nicht „ping funktioniert“ als Beweis für API-Erreichbarkeit. Ping zeigt nur, dass der Host erreichbar ist, nicht dass TLS, Zertifikat und Pfad stimmen.

6. Streaming-Abbrüche und Kontextüberschreitung

Streaming-Abbrüche treten typischerweise in drei Fällen auf: Ein Proxy puffert SSE, die Verbindung läuft im Leerlauf in ein Timeout, oder das Modell wird während der Generierung gedrosselt. Das äußert sich als halbe Antwort, stream ended unexpectedly oder ein dauerhaft drehender Cursor.

Diagnose:

Senden Sie dieselbe Anfrage zuerst mit "stream": false. Funktioniert die nicht gestreamte Variante, liegt das Problem im Streaming-Pfad oder Proxy.
Testen Sie mit curl -N direkt, um den Cursor-Client als Ursache auszuschließen.
Senken Sie max_tokens und die Kontextlänge und beobachten Sie, ob der Abbruch bleibt.
Prüfen Sie, ob der Proxy Response-Buffering aktiviert hat; gegebenenfalls die API-Domain direkt ansprechen.
Für lange Agent-Aufgaben Timeouts und maximale Runden setzen, damit Verbindungen nicht hängen bleiben.

Eine Kontextüberschreitung liefert meist 400 oder 413; im Fehlerkörper erscheinen context_length_exceeded oder maximum context length. Cursor sendet geöffnete Dateien, abgerufene Fragmente und den Gesprächsverlauf gemeinsam, sodass der tatsächliche Kontext oft länger ist als erwartet. Gegenmaßnahmen: Build-Artefakte und Logs über Ignore-Dateien ausschließen, unnötige Tabs schließen, lange Dokumente vorher zusammenfassen und für lange Gespräche eine neue Sitzung beginnen.

7. Logs, die dem Support wirklich helfen

Erfassen Sie mindestens: Zeitpunkt, Statuscode, Fehlercode, Modell-ID, Hostname der Base URL, Request-ID, Dauer und Anzahl der Retries. Die Request-ID steht meist im Antwort-Header, etwa als request-id, x-request-id oder x-oneapi-request-id; maßgeblich ist, was das Gateway tatsächlich liefert.

Ein brauchbares Log sieht so aus:

2026-10-19T10:12:33+08:00 status=429 code=rate_limit_exceeded model=IhreModellID host=api.zhongshangqihang.com request_id=... latency_ms=1840 retry=2

Protokollieren Sie niemals den vollständigen Key, vollständige Prompts oder Nutzercode. Vom Key nur die ersten und letzten vier Zeichen behalten, sensible Inhalte maskieren. Für den Support ist ein Log mit Request-ID nützlicher als zehn Screenshots.

8. Checkliste für die Support-Diagnose

Fehlertext, Statuscode, Zeitpunkt und Request-ID notieren.
Dieselbe Anfrage mit curl reproduzieren und prüfen, ob das Problem nur in Cursor auftritt.
Base URL prüfen: OpenAI-kompatibel meist bis /v1, Claude Code mit der Root-Adresse.
Modell-ID prüfen: aus der Modellliste kopieren, Schreibweise und Version bestätigen.
Einen neuen Key testen, um abgelaufene Keys, Kontingente oder Teamrichtlinien auszuschließen.
Zuerst nicht gestreamt und mit kurzem Kontext testen, dann Streaming und langen Kontext schrittweise hinzufügen.
Netzwerk oder Proxy wechseln, um DNS, TLS und Unternehmensproxy auszuschließen.
Wenn alles passt, Logs und Reproduktionsschritte an den Gateway- oder Cursor-Support geben.

9. Häufige Fragen

Der Key funktioniert anderswo, in Cursor aber 401?

Prüfen Sie zuerst, ob er im falschen Provider-Feld steht, dann, ob die Base URL zur Umgebung des Keys passt. In der Teamversion außerdem bestätigen, dass Administratoren persönliche Drittanbieter-Keys nicht gesperrt haben.

Bedeutet 404 immer, dass das Modell abgeschaltet wurde?

Nein. Meist fehlt oder doppelt sich /v1 in der Base URL, oder die Modell-ID ist falsch geschrieben. Rufen Sie die Modellliste auf und kopieren Sie die ID.

Ist 429 ein Zeichen für zu wenig Guthaben?

Nicht unbedingt. 429 zeigt eine überschrittene Rate oder ein erschöpftes Kontingent; fehlendes Guthaben kann je nach Gateway 401, 402 oder 403 liefern. Maßgeblich sind Fehlerkörper und Abrechnungsseite.

Lassen sich Claude-Modelle direkt in Cursor nutzen?

Ja, über einen Anthropic-Key oder über ein kompatibles Gateway mit OpenAI-Protokoll. In gängigen Versionen bietet das Anthropic-Feld keine Base-URL-Überschreibung; für ein Gateway wählt man üblicherweise OpenAI Compatible und trägt die exakte Modell-ID ein.

Warum schlagen nur Streaming-Anfragen fehl?

Verdächtig sind Proxy-Buffering, Idle-Timeouts und Verbindungs-Reuse. Vergleichen Sie mit einer nicht gestreamten Anfrage und testen Sie direkt mit curl -N; damit lässt sich der Abschnitt im Pfad meist eingrenzen.

Nächste Schritte

Erstellen Sie zunächst im ZSQH AI Gateway einen Test-Key und führen Sie Authentifizierung, Modellaufruf und Streaming mit den curl-Befehlen aus diesem Artikel durch, bevor Sie ihn in Cursor eintragen. Modellverfügbarkeit und Preise entnehmen Sie den Modellpreisen. Beim Debugging gilt: erst Variablen fixieren, dann einzeln ersetzen.

Weiterlesen:

Hinweis: Cursor ist eine Marke von Anysphere, Inc.; OpenAI, Anthropic, Claude und Google sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient ausschließlich der technischen Fehlersuche; es besteht keine Zugehörigkeit oder Partnerschaft mit den genannten Unternehmen. Fehlertexte, Menüs und Schnittstellenverhalten können sich mit Versionen ändern; maßgeblich ist die offizielle Dokumentation.