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

Wenn Roo Code an eine Drittanbieter-API angebunden wird, sind die meisten Fehler keine Frage der Modellfähigkeit, sondern von Anbieterauswahl, Base URL, Key, Rate Limits oder Netzwerk. Typische Symptome: direkt nach dem Einrichten ein 401, nach dem Ändern der Adresse ein 404, eine lange Aufgabe bricht zur Hälfte mit 429 ab, oder das Streaming hängt bis zum Timeout. Die richtige Reihenfolge lautet: zuerst Statuscode und Fehlertyp prüfen, dann die request-id, und erst zuletzt den Prompt ändern. Dieser Artikel behandelt 401, 404, 429, Kontextüberschreitung und Timeouts mit Prüfschritten, Log-Checkliste und Beispielcode. Modelle und Abrechnung entnehmen Sie den Modellpreisen.

1. Zuerst schichten: Auf welcher Ebene tritt der Fehler auf?

Eine Anfrage durchläuft den Roo-Code-Client, den VS-Code-Erweiterungshost, Netzwerk und Proxy, das Gateway und das vorgelagerte Modell. Derselbe 401 kann ein falscher Key sein oder ein nicht passendes Anbieterprotokoll; derselbe 404 kann ein zusätzliches /v1 im Pfad oder eine nicht existierende Modell-ID sein. Eine saubere Schichtung verhindert, dass Sie in die falsche Richtung konfigurieren.

Statuscode	Fehlertyp	Häufige Ursache	Vorgehen
400	invalid_request_error	Parameter, Kontextlänge oder Ausgabenlimit	Anfrage ändern oder Limit anpassen, dann wiederholen
401	authentication_error	Key fehlt, falsch, abgelaufen oder Auth-Header passt nicht	Zugangsdaten korrigieren, nicht wiederholen
402	billing_error	Problem mit Rechnung oder Guthaben	Abrechnung prüfen
403	permission_error	Key hat keine Modell- oder Projektberechtigung	Berechtigung prüfen
404	not_found_error	Pfad oder Modell-ID falsch	Base URL und Modellname prüfen
413	request_too_large	Anfragekörper überschreitet das Limit	Komprimieren oder aufteilen
429	rate_limit_error	Frequenz, Parallelität oder Ausgabenlimit	Mit Backoff wiederholen
500	api_error	Interner Serverfehler	Mit Backoff wiederholen
504	timeout_error	Verarbeitungs-Timeout	Streaming oder Aufteilung ändern

Die request-id aus Antwort-Headern oder Fehlerkörpern sollte aufbewahrt werden. Das Protokoll erfasst mindestens Zeitpunkt, Statuscode, Fehlertyp, Modell-ID und Request-ID; vollständige Keys und sensibler Code gehören nicht hinein.

2. 401: Anbieter, Key und Auth-Header

In Roo Code sind die Anbieterauswahl und das Key-Feld getrennt. Der häufigste 401 entsteht nicht durch einen ungültigen Key, sondern durch eine falsche Kombination: ein OpenAI-kompatibler Key im Anthropic-Anbieter oder umgekehrt; eine Base URL, die auf Umgebung A zeigt, während der Key zu Umgebung B gehört; ein alter Key, der nach dem Wechsel des Konfigurationsprofils stehen geblieben ist.

Weitere häufige Ursachen: Leerzeichen, Zeilenumbrüche, Anführungszeichen oder Vollbreitezeichen vor und nach dem Key; ein gelöschter, abgelaufener oder zu einem anderen Arbeitsbereich gehörender Key; ein Unternehmensproxy, der den Authorization-Header umschreibt oder entfernt; gleichzeitig konfigurierte Abo-Anmeldung und API-Key in derselben Erweiterung.

Prüfreihenfolge:

Prüfen Sie, ob Anbietertyp und Protokoll der Base URL zusammenpassen: OpenAI-kompatibel über /v1/chat/completions, Anthropic über /v1/messages.
Senden Sie mit demselben Key und derselben Base URL eine minimale Anfrage direkt im Terminal.
Gelingt der Direktaufruf, scheitert Roo Code aber, liegt es an Anbieterkonfiguration, Profil oder Proxy. Scheitert auch der Direktaufruf, liegt es an Key, Gateway oder Netzwerk.
Testen Sie einen neuen Key als Gegenprobe, um Kopierfehler auszuschließen.

Ein 401 sollte nicht wiederholt werden; Wiederholungen blähen nur Protokolle und Warnungen auf.

3. 404: Base-URL-Pfad und Modell-ID

404 hat zwei Ursachenklassen: Der Pfad existiert nicht, oder das Modell existiert nicht.

Pfadprobleme: Bei einem OpenAI-kompatiblen Anbieter endet die Base URL üblicherweise bei /v1, und der Client ergänzt /chat/completions. Tragen Sie den vollständigen Pfad /v1/chat/completions ein, kann ein doppelter Pfad entstehen. Ein abschließender Schrägstrich, doppelte Schrägstriche, Groß- und Kleinschreibung sowie überflüssige Leerzeichen können ebenfalls 404 auslösen. Der Anthropic-Anbieter ergänzt /v1/messages; eine OpenAI-kompatible Adresse führt dort ebenso zu 404.

Modellprobleme: Erscheint model not found, invalid model oder The model does not exist, kopieren Sie die exakte ID aus der Modellliste des Gateways oder von der Preisseite. Aliasnamen, Datumssuffixe und Schreibweise können abweichen; manche Gateways verlangen ein Anbieterpräfix. Prüfen Sie außerdem, ob der Key für dieses Modell berechtigt ist – fehlende Rechte liefern teils 403, teils 404.

Schnellprüfung: Rufen Sie /v1/models auf, sehen Sie die für den Key sichtbaren Modelle und senden Sie mit einer ID aus dieser Liste eine minimale Anfrage.

4. 429: Rate Limits, Kontingente und Wiederholungsstürme

429 bedeutet, dass eine Frequenz-, Parallelitäts- oder Ausgabengrenze überschritten wurde. Häufige Ursachen:

Anfragen oder Tokens pro Minute überschritten;
mehrere Werkzeuge oder Kollegen teilen einen Key;
Orchestrator-Unteraufgaben oder parallele Tool-Aufrufe erhöhen die momentane Parallelität;
Wiederholungen ohne Backoff erzeugen einen Wiederholungssturm;
Guthaben oder Ausgabenlimit des Arbeitsbereichs greift.

Prüfen Sie zuerst den Header retry-after: Ist er vorhanden, warten Sie entsprechend; fehlt er, verwenden Sie exponentielles Backoff mit zufälligem Jitter und einer Höchstzahl. Manche kontingentbedingten 429 enthalten kein retry-after; Warten allein hilft dann nicht, sondern es braucht eine Aufladung oder eine Anpassung des Limits.

Beachten Sie überlagerte Wiederholungsebenen: Roo Code, SDK und Gateway können jeweils selbst wiederholen, und eine eigene Geschäftslogik kommt hinzu. Die tatsächliche Anfragenzahl vervielfacht sich. Planen Sie Client-, SDK- und Geschäftslogik gemeinsam. Bei 401, 403, 404 und 400 nicht wiederholen.

5. 400 und 413: Kontextlänge und Anfragekörper

Eine Kontextüberschreitung liefert meist 400 mit Begriffen wie context length, maximum context oder prompt is too long. Ursache ist nicht ein defektes Modell, sondern ein Budget aus Input und Output, das das Fenster übersteigt.

In Roo Code ist die Einstellung des Kontextfensters besonders wichtig: Ist der manuell eingetragene Wert größer als die tatsächliche Modellfähigkeit, kürzt der Client nach falschem Budget oder sendet zu lange Anfragen – Ergebnis 400. Setzen Sie das Fenster auf den in der Modelldokumentation angegebenen Wert und aktivieren Sie, falls die Version es unterstützt, Kontextkomprimierung beziehungsweise Condensing.

Vorgehen:

Weniger Dateien auf einmal einlesen, nur relevante Ausschnitte übergeben.
Terminalausgaben und MCP-Tool-Rückgaben komprimieren, nur notwendige Felder behalten.
Lange Dokumente kapitelweise aufteilen, abschnittsweise verarbeiten und danach zusammenführen.
Frühe Gesprächsrunden bereinigen, Systemprompt, letzte Runden und Zusammenfassung behalten.
Platz für die Ausgabe lassen; max_tokens begrenzt nur den Output und löst keine Input-Überschreitung.

413 request_too_large bezeichnet einen zu großen Anfragekörper und ist nicht dasselbe wie Kontextlänge. Screenshots, PDFs und Base64-Bilder lösen ihn am häufigsten aus; Bilder komprimieren, Anhänge reduzieren oder Anfragen aufteilen.

6. Timeouts und Abbrüche: Streaming, Proxy und lange Aufgaben

Roo Code verwendet standardmäßig Streaming. Eine Streaming-Antwort kann zunächst HTTP 200 liefern und danach im SSE-Ereignisstrom ein Fehlerereignis senden; ein Client, der nur den Statuscode prüft, hält den Fehlschlag für Erfolg. Der Ereignisstrom muss auf Fehler geprüft und ein reguläres Endsignal bestätigt werden, sonst ist das Ergebnis unvollständig.

Häufige Timeout-Ursachen:

Unternehmensproxy, VPN oder TLS-Interception führen zu instabilen Verbindungen;
DNS-, IPv6-, Firewall- oder MTU-Probleme;
eine einzelne Anfrage dauert zu lange, die Leerlaufverbindung wird getrennt;
ein langer Agent-Lauf führt kontinuierlich Tools aus und überschreitet die Zeitgrenze von Client oder Gateway;
das vorgelagerte Modell steht in der Warteschlange, das erste Byte kommt spät.

Bevorzugen Sie Streaming, setzen Sie ein sinnvolles Timeout pro Anfrage, teilen Sie lange Aufgaben in Phasen, begrenzen Sie automatisch freigegebene Tools und testen Sie bei Verdacht auf ein lokales Netzwerkproblem einen anderen Netzzugang oder einen Mobilfunk-Hotspot. Bei unternehmensweiter TLS-Interception müssen VS Code und das System der entsprechenden CA vertrauen; Node-basierte Clients benötigen mitunter NODE_EXTRA_CA_CERTS.

7. Protokolle und Support: Das Problem verständlich beschreiben

Senden Sie nicht nur „es gibt einen Fehler“. Sammeln Sie folgende Angaben:

Zeitpunkt, Zeitzone und Dauer.
Roo-Code-Version, VS-Code-Version und Betriebssystem.
Anbietertyp, Base URL (nur Domain) und Modell-ID.
Ob Streaming aktiv war, Laufzeit der Anfrage und Anzahl der Wiederholungen.
HTTP-Statuscode, Fehlertyp und vollständige Fehlermeldung.
request-id aus Antwort-Header und gegebenenfalls Antwortkörper.
Betroffener Bereich: ein Rechner, ein Projekt, ein Netzwerk oder das gesamte Team.
Minimale Reproduktion: ein curl-Aufruf oder ein kleines Repository sowie das Ergebnis derselben Anfrage am offiziellen Endpunkt.

Log-Ort: Im Output-Bereich von VS Code nach dem Roo-Code-Kanal suchen; Fehler von Erweiterungshost und MCP-Tools finden sich eventuell in der Developer-Tools-Konsole; bei Gateway-Problemen die Request-ID an den Gateway-Support geben. Nach der Archivierung des Haupt-Repositories können GitHub-Issues schreibgeschützt sein; prüfen Sie zunächst die Supportkanäle des verwendeten Community-Zweigs. Bei der Anonymisierung konkrete Regeln anwenden: vom Key nur die ersten und letzten vier Zeichen behalten, Prompts und Code nach Unternehmensvorgabe behandeln.

8. Beispiel: Wiederholung nach Fehlertyp entscheiden

Das folgende Beispiel verwendet eine OpenAI-kompatible Schnittstelle: 401 und 404 schlagen sofort fehl, 429, 5xx und Timeouts werden mit Backoff wiederholt. Es dient sowohl als eigenständiges Skript zur Reproduktion als auch als Baustein für eigene Batch-Aufgaben.

import os
import random
import time

from openai import (
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    AuthenticationError,
    NotFoundError,
    OpenAI,
    RateLimitError,
)

client = OpenAI(
    base_url=os.environ["OPENAI_BASE_URL"],
    api_key=os.environ["OPENAI_API_KEY"],
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model=os.environ["OPENAI_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                timeout=120,
            )
            return resp.choices[0].message.content or ""
        except AuthenticationError as exc:
            raise SystemExit(f"401: Anbieter, Key und Auth-Header prüfen, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404: Base URL und Modell-ID prüfen, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429: warte {wait:.1f}s und wiederhole")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Timeout oder Verbindungsfehler: warte {wait:.1f}s und wiederhole")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}: warte {wait:.1f}s und wiederhole")
                time.sleep(wait)
                continue
            raise

    raise RuntimeError("Wiederholungen erschöpft, auf Fallback oder Alarm wechseln")

print(ask("Antworte nur mit OK"))

Das Beispiel setzt die SDK-Wiederholungen nicht ausdrücklich; in der Produktion müssen SDK-Standardwiederholungen und eigene Wiederholungen gemeinsam konfiguriert werden. Die Base URL lautet üblicherweise https://ai.zhongshangqihang.com/v1, die Modell-ID kopieren Sie aus den Modellpreisen.

Häufige Fragen

Bedeutet 401 immer einen falschen Key?

Nein. Ein nicht passender Anbietertyp, eine Base URL auf die falsche Umgebung oder ein Proxy, der den Auth-Header umschreibt, führen ebenfalls zu 401. Testen Sie zuerst mit demselben Key und derselben Base URL direkt und prüfen Sie danach Anbieter und Profil in Roo Code.

Wie bestätige ich bei 404 die richtige Modell-ID?

Rufen Sie /v1/models auf, kopieren Sie die exakte ID aus der für den Key sichtbaren Liste und schreiben Sie sie nicht aus dem Gedächtnis. Prüfen Sie anschließend, ob die Base URL den Pfad doppelt enthält und ob das Anbieterprotokoll passt.

Erholt sich ein 429 nach kurzer Wartezeit immer?

Nicht unbedingt. Frequenzlimits erholen sich meist; ein kontingent- oder guthabenbedingter 429 enthält oft kein retry-after, sodass Warten nutzlos ist und Limit oder Guthaben angepasst werden müssen. Entscheiden Sie nach Fehlertyp und Antwort-Headern.

Ist eine Kontextüberschreitung ein Modellproblem?

Meist nicht. Entweder übersteigt das Budget aus Input und Output das Fenster, oder das in Roo Code eingetragene Kontextfenster ist größer als die tatsächliche Modellfähigkeit. Eingaben reduzieren, Komprimierung aktivieren und Aufgaben aufteilen hilft direkter als ein Modellwechsel.

Gilt eine Streaming-Antwort mit 200 und anschließendem Abbruch als Erfolg?

Nein. Nach dem 200 kann im SSE-Strom ein Fehlerereignis folgen. Der Client muss den Ereignisstrom auswerten und ein reguläres Ende bestätigen; andernfalls wird das Ergebnis als unvollständig markiert und wiederholt oder gemeldet.

Nächste Schritte

Legen Sie zunächst in der ZSQH AI Gateway einen Test-Key an und spielen Sie mit dem obigen curl-Aufruf und Skript je einmal 401, 404, 429 und einen Timeout durch, bevor Sie die Produktionsüberwachung anbinden. Modellverfügbarkeit und Abrechnung entnehmen Sie den Modellpreisen.