Cline API-Fehler: 401, 404, 429 und Timeouts (2026)

Cline ist ein verbreiteter Open-Source-Programmieragent in VS Code. Bei der Anbindung einer eigenen API wählen die meisten in den Einstellungen OpenAI Compatible und tragen Base URL, API-Key und Modell-ID ein. Fehler konzentrieren sich meist auf vier Ebenen: Zugangsdaten, Pfad, Ratenbegrenzung und Netzwerk. Wer bei der ersten roten Meldung sofort das Modell wechselt, zieht aus einem zehnminütigen Konfigurationsproblem oft einen halben Tag.

Sinnvoller ist diese Reihenfolge: zuerst Statuscode und Fehlerkörper lesen, dann mit einer minimalen Anfrage reproduzieren und erst danach Modell, Kontext oder Prompt ändern. Dieser Beitrag ordnet 401, 404, 429, Kontextüberschreitung, Tool-Aufrufe und Timeouts einzeln ein und nennt die Logpfade von Cline sowie eine Checkliste für den Support.

Hinweis: Cline ist eine Marke von Cline Bot Inc.; VS Code ist eine Marke der Microsoft Corporation; OpenAI ist eine Marke von OpenAI, Inc. Dieser Beitrag dient ausschließlich der technischen Erläuterung; es besteht keine Zugehörigkeit oder Kooperation mit den genannten Unternehmen. Oberfläche, Menüs und Fehlertexte können sich mit Versionen ändern; maßgeblich ist die installierte Version.

1. Reihenfolge der Fehlersuche: erst Schichten, dann Konfiguration

Symptom oder Statuscode	Häufige Bedeutung	Zuerst prüfen	Wiederholen?
401	Key fehlt, ist falsch oder abgelaufen	Key, Provider-Feld, Kontostatus	Nein
403	Key ohne Berechtigung oder durch Richtlinie blockiert	Modellrechte, Teameinstellungen, Guthaben	Nein
404	Falscher Pfad oder Modell existiert nicht	Base URL, Modell-ID	Nein
429	Anfragefrequenz, Parallelität oder Kontingent überschritten	Verbrauch, geteilte Keys, Retry-Strategie	Nach Backoff
400/413	Fehlerhaftes Anfrageformat oder Kontext zu lang	Kontext, Parameter, max_tokens	Nach Anpassung
Timeout oder Stream-Abbruch	Proxy, TLS, Idle-Timeout, Überlastung des Servers	Netzwerkpfad, Streaming-Einstellungen	Situationsabhängig
Tool-Aufruf schlägt fehl	Modell oder Gateway unterstützt das Tool-Protokoll nicht	Modellfähigkeit, Schnittstellenkompatibilität	Nein

Bei der Suche gilt: gleicher Key, gleiche Base URL, gleiche Modell-ID, und immer nur eine Änderung auf einmal. Wer drei Stellen gleichzeitig ändert, weiß auch nach der Behebung nicht, welche den Ausschlag gab.

2. 401 und 403: zuerst Key, dann das Provider-Feld

In der Provider-Liste von Cline stehen sowohl OpenAI als auch OpenAI Compatible. Für ein Dritt-Gateway ist normalerweise Letzteres richtig. Bei der falschen Auswahl kann die Anfrage weiterhin an die Standardadresse von OpenAI gehen, und der eigene Key wird dort natürlich nicht akzeptiert.

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 Chatfenstern geraten besonders leicht unsichtbare Zeichen hinein.
Steht der Key im richtigen Provider-Formular? Die Felder verschiedener Provider sind in Cline getrennt; an der falschen Stelle führt der Key direkt zu 401.
Wurde der Key gelöscht, deaktiviert oder ist er abgelaufen? Maßgeblich ist der Status in der Gateway-Konsole.
Hat das Konto ausreichend Guthaben? Bei zu wenig Guthaben können 401, 402 oder 403 zurückkommen; entscheidend ist der Fehlerkörper.
Zeigt die Base URL auf die Umgebung, zu der der Key gehört? Ein Test-Key an einer Produktionsadresse ergibt meist ebenfalls 401.
Beschränkt die Teamversion persönliche Keys oder Dritt-Endpunkte? Greift eine solche Richtlinie, scheitert auch eine lokal korrekte Konfiguration.

Prüfen Sie Adresse und Key zuerst mit einer minimalen Anfrage:

export API_KEY="sk-ihr-schluessel"

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

head -c 300 /tmp/cline_models.json

Ein 200 bedeutet, dass Adresse, Key und Protokoll grundsätzlich funktionieren. Bei 401 testen Sie denselben Key im Testbereich der Gateway-Konsole. So lässt sich unterscheiden, ob der Key selbst das Problem ist oder ein Feld beziehungsweise die Netzwerkschicht von Cline.

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

Ein 404 bedeutet nicht zwangsläufig, dass das Modell abgeschaltet wurde. Am häufigsten ist ein falsch zusammengesetzter Pfad:

Die Base URL lässt /v1 weg; die Anfrage landet auf einer Web-Route und liefert HTML oder 404.
Die Base URL enthält zusätzlich /v1/chat/completions, und der Client hängt den Pfad noch einmal an.
Der Anthropic-Pfad /v1/messages steht in einem OpenAI-kompatiblen Feld oder umgekehrt.
Groß- und Kleinschreibung, Bindestriche oder Versionssuffix der Modell-ID weichen vom Gateway ab.
Das Modell ist für das aktuelle Konto, den Tarif oder die Region nicht freigeschaltet.

Die Schaltfläche Verify in Cline prüft vor allem die Erreichbarkeit von Adresse und Key; sie belegt nicht, dass jedes Modell für das Konto offen ist. Eine echte Dialoganfrage bleibt nötig. Liefert /v1/models eine Liste, die eigentliche Unterhaltung aber 404, verdächtigen Sie zuerst die Modell-ID und nicht den Key. Am sichersten kopieren Sie die ID aus der Modellliste oder von der Seite Modellpreise, statt sie abzutippen.

4. 429: Ratenlimit, Parallelität und Kontingent sind nicht dasselbe

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

Anfragen pro Minute oder Tokens pro Minute sind überschritten.
Mehrere Personen teilen einen Key und verdrängen sich gegenseitig.
Der Agent liest nacheinander Dateien und führt Befehle aus, wodurch in kurzer Zeit sehr viele Anfragen entstehen.
Wiederholungen laufen ohne Backoff und verstärken den Fehler zu einem Retry-Sturm.
Lange Kontextanfragen belegen viel Kontingent und lassen weniger Raum für parallele Anfragen.

Lesen Sie zuerst Antwort-Header und Fehlerkörper. Gibt es Retry-After, warten Sie entsprechend; sonst verwenden Sie exponentielles Backoff mit zufälligem Jitter. 401 und 404 sollten nicht wiederholt werden; Wiederholungen vergrößern das Problem nur. Hier ein wiederverwendbares Beispiel:

import random
import time
import httpx

RETRYABLE = {429, 500, 502, 503, 504}

def chat(payload, key, url="https://ai.zhongshangqihang.com/v1/chat/completions"):
    for attempt in range(4):
        try:
            resp = httpx.post(
                url,
                json=payload,
                headers={"Authorization": f"Bearer {key}"},
                timeout=httpx.Timeout(120.0, connect=10.0),
            )
        except httpx.TimeoutException:
            if attempt == 3:
                raise
            time.sleep(min(30, 2 ** attempt) + random.random())
            continue

        if resp.status_code in (400, 401, 403, 404, 413):
            raise RuntimeError(f"{resp.status_code}: {resp.text[:300]}")

        if resp.status_code in RETRYABLE:
            retry_after = resp.headers.get("Retry-After", "")
            wait = float(retry_after) if retry_after.isdigit() else 2 ** attempt
            time.sleep(min(30, wait) + random.random())
            continue

        resp.raise_for_status()
        data = resp.json()
        choice = data["choices"][0]
        if choice.get("finish_reason") == "error":
            raise RuntimeError(f"stream error: {choice.get('error')}")
        return data

    raise RuntimeError("Wiederholungsbudget ausgeschöpft")

Der Code trennt nicht wiederholbare Authentifizierungs- und Pfadfehler von wiederholbaren Raten- und Serverfehlern. Bei Streaming-Antworten kann der Fehler in finish_reason stecken, während der HTTP-Status weiterhin 200 lautet; das muss separat geprüft werden. Produktiver Code sollte außerdem das HTTP-Datumsformat von Retry-After akzeptieren, damit die direkte Umwandlung in eine Zahl nicht scheitert.

5. Kontextüberschreitung und fehlgeschlagene Tool-Aufrufe

Eine Kontextüberschreitung liefert meist 400 oder 413; im Fehlerkörper erscheinen Begriffe wie context_length_exceeded oder maximum context length. Cline sendet geöffnete Dateien, Terminalausgaben, Suchtreffer und den Gesprächsverlauf gemeinsam, sodass der tatsächliche Kontext oft länger ist als erwartet.

In der Model Configuration von Cline müssen Context Window und Max Output Tokens häufig manuell bestätigt oder eingetragen werden. Ist der Wert größer als die tatsächliche Fähigkeit, kann die Anfrage abgelehnt werden; ist er zu klein, komprimiert Cline den Kontext früher. Hilfreich sind: eine neue Aufgabe beginnen, Build-Artefakte und Logs ausschließen, unnötige Tabs schließen, lange Dokumente vorher zusammenfassen und lange Gespräche neu starten.

Fehlgeschlagene Tool-Aufrufe sind eine eigene Klasse. Ein OpenAI-kompatibler Endpunkt muss nicht nur chatten können, sondern auch das native tools/function-calling-Protokoll unterstützen. Manche Gateways oder Modelle implementieren nur die Grundunterhaltung: Normale Fragen funktionieren, doch sobald der Agent eine Datei liest, kommt 400 oder ein anderer Fehler. Prüfen Sie dann zuerst, ob nur Tool-Aufrufe scheitern, und untersuchen Sie anschließend die Tool-Fähigkeit des Modells sowie die Konfiguration von Computer Use in Cline.

6. Timeouts, Stream-Abbrüche und Verbindungsfehler

Timeouts liefern oft keinen HTTP-Status. Stattdessen bleibt die Anfrage lange ohne Antwort, endet mit ECONNRESET, einem Zertifikatsfehler oder einer halben Antwort. Häufige Ursachen:

Ein Unternehmensproxy oder eine Firewall setzt für langlebige Verbindungen ein Idle-Timeout.
Der Proxy puffert SSE, sodass Streaming-Daten nicht rechtzeitig weitergeleitet werden.
VPN, Sicherheitssoftware oder DNS blockieren die API-Domain.
Die Systemzeit weicht stark ab, wodurch die TLS-Zertifikatsprüfung scheitert.
Die Agent-Aufgabe ist zu lang und überschreitet das Timeout von Client oder Gateway.

Senden Sie zur Diagnose dieselbe Anfrage zuerst mit "stream": false. Klappt die nicht gestreamte Variante, liegt das Problem im Streaming-Pfad oder Proxy. Testen Sie danach direkt mit curl -N, um Cline als Ursache auszuschließen. Führt ein Unternehmensproxy eine TLS-Inspektion durch, muss das Firmen-Stammzertifikat in die Vertrauenskette aufgenommen werden; gegebenenfalls ist NODE_EXTRA_CA_CERTS zu setzen. http.proxyStrictSSL zu deaktivieren ist nur ein vorübergehendes Mittel und für Produktion nicht empfehlenswert. Ein erfolgreicher ping belegt ebenfalls nicht, dass die API nutzbar ist, denn er prüft weder TLS noch Zertifikat noch Pfad.

7. Logs und Diagnose: erst Belege sichern, dann fragen

Öffnen Sie in VS Code View → Output und wählen Sie im Auswahlfeld den Kanal Cline, um die Live-Logs der Erweiterung zu sehen. In der CLI liegen die Logs üblicherweise unter ~/.cline/data/logs/cline.log und lassen sich mit cline doctor log öffnen; bei JetBrains ist häufig ~/.cline/cline-core-service.log relevant. Maßgeblich sind die Pfade der aktuellen Version.

Ein brauchbarer Eintrag enthält mindestens: Zeitpunkt, Statuscode, Fehlercode, Modell-ID, Hostname der Base URL, Request-ID, Dauer und Anzahl der Wiederholungen. Die Request-ID steht meist in den Antwort-Headern, etwa als request-id, x-request-id oder in einem gateway-spezifischen Feld. Für den Support ist ein Log mit Request-ID nützlicher als zehn Screenshots.

Protokollieren Sie niemals den vollständigen Key, den vollständigen Prompt oder Kundencode. Vom Key bleiben nur die ersten und letzten vier Zeichen; sensible Inhalte werden maskiert. Auch Logs können Codefragmente enthalten und sollten vor dem Teilen geprüft werden.

8. Checkliste für den Support

Fehlertext, Statuscode, Zeitpunkt und Request-ID notieren.
Mit curl /v1/models aufrufen und prüfen, ob Adresse und Key funktionieren.
Kontrollieren, ob die Base URL bei /v1 endet und der Pfad nicht doppelt angehängt wird.
Modell-ID aus der Modellliste kopieren und Schreibweise sowie Versionssuffix prüfen.
Mit einem 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 ergänzen.
Netzwerk oder Proxy wechseln, um DNS, TLS und Unternehmensproxy auszuschließen.
Erst wenn all das bestanden ist, Logs, Reproduktionsschritte und Request-ID an den Gateway- oder Cline-Support geben.

9. Häufige Fragen

Der Key funktioniert anderswo, in Cline aber nicht?

Prüfen Sie zuerst, ob als Provider OpenAI Compatible gewählt ist, und dann, ob die Base URL zur Umgebung des Keys passt. In der Teamversion ist außerdem zu klären, ob persönliche Keys eingeschränkt sind.

Bedeutet 404 immer, dass das Modell abgeschaltet wurde?

Nein. Meist fehlt /v1 in der Base URL, ist ein zusätzliches /v1 vorhanden oder die Modell-ID falsch geschrieben. Rufen Sie die Modellliste auf und testen Sie mit kopierter ID.

Ist 429 ein Zeichen für zu wenig Guthaben?

Nicht unbedingt. 429 steht für überschrittene Rate, Parallelität oder ein überschrittenes Kontingent. Zu wenig Guthaben kann 401, 402 oder 403 liefern; maßgeblich ist der Fehlerkörper.

Warum schlagen nur Streaming-Anfragen fehl?

Verdächtigen Sie zuerst Proxy-Pufferung, Idle-Timeouts und Verbindungs-Wiederverwendung. Vergleichen Sie mit einer nicht gestreamten Anfrage und testen Sie danach direkt mit curl -N.

Wo finde ich die Cline-Logs?

In VS Code unter View → Output → Cline; in der CLI unter ~/.cline/data/logs/cline.log oder über cline doctor log. Je nach Version und Plattform kann der Pfad abweichen; maßgeblich ist die aktuelle Dokumentation.

Nächster Schritt

Erstellen Sie zunächst einen Test-Key im ZSQH AI Gateway und spielen Sie mit den curl-Befehlen aus diesem Beitrag Authentifizierung, Modell und Streaming durch, bevor Sie die Werte in Cline eintragen. Modellverfügbarkeit und Preise entnehmen Sie den Modellpreisen. Bei der Fehlersuche gilt: Variablen fixieren und dann eine nach der anderen ersetzen.