Lors de l'intégration d'une API tierce à Roo Code, la plupart des erreurs ne relèvent pas des capacités du modèle, mais du choix du fournisseur, de la Base URL, de la clé, de la limitation de débit ou du réseau : un 401 dès la configuration, un 404 après un changement d'adresse, un 429 au milieu d'une tâche longue, un flux bloqué jusqu'au délai d'attente. L'ordre de traitement est simple : d'abord le code de statut et le type d'erreur, ensuite le request-id, et seulement enfin le prompt. Cet article détaille 401, 404, 429, le dépassement de contexte et les délais, avec des étapes de diagnostic, une liste de journaux et un exemple de code. Modèles et facturation font foi sur la page tarifs des modèles.

1. D'abord situer la couche où survient l'erreur

Une requête traverse le client Roo Code, l'hôte d'extension VS Code, le réseau et le proxy, la passerelle, puis le modèle amont. Un même 401 peut venir d'une clé erronée ou d'un protocole de fournisseur incompatible ; un même 404 peut venir d'un /v1 en trop dans le chemin ou d'un identifiant de modèle inexistant. Situez d'abord la couche pour éviter de modifier la configuration dans la mauvaise direction.

Statut Type d'erreur Cause fréquente Traitement
400 invalid_request_error Paramètres, longueur de contexte ou plafond de dépense Corriger la requête ou le quota, puis réessayer
401 authentication_error Clé absente, erronée, expirée, en-tête d'authentification incompatible Corriger l'identifiant, ne pas réessayer
402 billing_error Problème de facturation ou de solde Vérifier la facturation
403 permission_error Clé sans droit sur le modèle ou le projet Vérifier les droits d'accès
404 not_found_error Chemin ou identifiant de modèle erroné Vérifier la Base URL et le nom du modèle
413 request_too_large Corps de requête au-delà de la limite Compresser ou découper la requête
429 rate_limit_error Fréquence, concurrence ou plafond de dépense Attendre puis réessayer avec backoff
500 api_error Erreur interne du serveur Réessayer avec backoff
504 timeout_error Délai de traitement dépassé Passer en flux ou découper

Conservez le request-id présent dans les en-têtes ou le corps de la réponse d'erreur. Les journaux doivent au minimum contenir l'heure, le statut, le type d'erreur, l'identifiant du modèle et l'identifiant de requête ; ne journalisez jamais la clé complète ni du code sensible.

2. 401 : fournisseur, clé et en-tête d'authentification

Dans Roo Code, la liste des fournisseurs et le champ de clé sont distincts : le 401 le plus fréquent ne vient pas d'une clé invalide, mais d'une mauvaise combinaison — une clé compatible OpenAI saisie dans un fournisseur Anthropic, ou l'inverse ; une Base URL pointant vers l'environnement A avec une clé de l'environnement B ; une ancienne clé conservée après un changement de profil.

Autres causes courantes : espaces, retours à la ligne, guillemets ou caractères pleine largeur autour de la clé ; clé supprimée, expirée ou appartenant à un autre espace de travail ; proxy d'entreprise qui réécrit ou supprime l'en-tête Authorization ; connexion par abonnement et clé API configurées simultanément dans la même extension.

Ordre de diagnostic :

  1. Vérifiez la cohérence entre le type de fournisseur et le protocole de la Base URL : compatible OpenAI passe par /v1/chat/completions, Anthropic par /v1/messages.
  2. Envoyez une requête minimale directement depuis le terminal avec la même clé et la même Base URL.
  3. Si l'appel direct réussit mais Roo Code échoue, le problème vient de la configuration du fournisseur, du profil ou du proxy ; s'il échoue aussi, il vient de la clé, de la passerelle ou du réseau.
  4. Testez une nouvelle clé en recoupement pour écarter un problème de copier-coller.

Ne réessayez pas un 401 : cela ne fait qu'amplifier les journaux et les alertes.

3. 404 : chemin de Base URL et identifiant de modèle

Les 404 se divisent en deux catégories : chemin inexistant ou modèle inexistant.

Problème de chemin : pour un fournisseur compatible OpenAI, la Base URL s'arrête généralement à /v1, le client ajoutant /chat/completions. Si vous saisissez le chemin complet /v1/chat/completions, le chemin final peut être dupliqué. Une barre oblique finale, une double barre, une casse différente ou un espace superflu peuvent aussi produire un 404. Le fournisseur Anthropic ajoute /v1/messages : y saisir une adresse compatible OpenAI produit également un 404.

Problème de modèle : si le message contient model not found, invalid model ou The model does not exist, copiez l'identifiant exact depuis la liste de modèles de la passerelle ou la page des tarifs. Les alias, suffixes de date et casses peuvent varier ; certaines passerelles exigent un préfixe de fournisseur. Vérifiez aussi que la clé a bien accès à ce modèle : un droit insuffisant renvoie parfois 403, parfois 404.

Vérification rapide : appelez /v1/models pour voir les modèles visibles par la clé, puis envoyez une requête minimale avec un identifiant de cette liste.

4. 429 : limitation, quota et tempête de nouvelles tentatives

Un 429 signifie que la requête dépasse une limite de fréquence, de concurrence ou de dépense. Causes fréquentes :

  • nombre de requêtes ou de tokens par minute dépassé ;
  • plusieurs outils ou collègues partageant une même clé ;
  • sous-tâches de l'Orchestrator ou appels d'outils parallèles augmentant la concurrence instantanée ;
  • nouvelles tentatives sans backoff, formant une tempête ;
  • solde du compte ou plafond de dépense de l'espace de travail atteint.

Regardez d'abord l'en-tête retry-after : s'il existe, attendez la durée indiquée ; sinon, appliquez un backoff exponentiel avec gigue aléatoire et un nombre maximal de tentatives. Certains 429 liés au quota n'ont pas de retry-after : attendre ne rétablit rien, il faut recharger ou ajuster la limite.

Attention à l'empilement de deux niveaux de retry : Roo Code peut réessayer automatiquement, le SDK ou la passerelle aussi, et la couche métier ajoute parfois une troisième boucle ; le nombre réel de requêtes peut être multiplié. Planifiez ensemble les retries du client, du SDK et de l'application. Ne réessayez pas les 401, 403, 404 et 400.

5. 400 et 413 : longueur de contexte et corps de requête

Un dépassement de contexte renvoie généralement un 400, avec des mentions comme context length, maximum context ou prompt is too long. Le modèle n'est pas en cause : le budget entrée plus sortie dépasse la fenêtre.

Dans Roo Code, faites particulièrement attention au réglage de la fenêtre de contexte : si la valeur saisie dépasse la capacité réelle du modèle, le client découpe selon un budget erroné ou envoie directement une requête trop longue, d'où le 400. Remplacez la valeur par celle indiquée dans la documentation du modèle et activez la compression ou le condensing du contexte si la version le permet.

Ordre de traitement :

  1. Réduisez le nombre de fichiers lus d'un coup et ne fournissez que les extraits pertinents.
  2. Compressez la sortie du terminal et les retours d'outils MCP, en ne gardant que les champs nécessaires.
  3. Découpez les longs documents par chapitre et traitez-les par étapes avant de synthétiser.
  4. Nettoyez le début de la conversation : conservez le système, les derniers tours et un résumé.
  5. Laissez de la place à la sortie ; max_tokens ne limite que la sortie et ne résout pas un dépassement d'entrée.

Le 413 request_too_large signifie un corps de requête trop volumineux, ce qui diffère d'une longueur de contexte excessive. Les captures d'écran, PDF et images base64 sont les plus souvent en cause ; compressez les images, réduisez les pièces jointes ou découpez la requête.

6. Délais et flux interrompus : streaming, proxy et tâches longues

Roo Code utilise le streaming par défaut. Une requête en flux peut renvoyer un HTTP 200 puis émettre un événement d'erreur dans le flux SSE ; un client qui ne regarde que le statut considère à tort la réponse comme réussie. Il faut analyser les événements d'erreur du flux et confirmer la réception du marqueur de fin normal, sinon marquer le résultat comme incomplet.

Sources fréquentes de délai :

  • proxy d'entreprise, VPN ou interception TLS rendant la connexion instable ;
  • problèmes de DNS, IPv6, pare-feu ou MTU ;
  • requête trop longue, connexion inactive coupée ;
  • tâche d'agent longue exécutant des outils en continu, dépassant la limite cumulée du client ou de la passerelle ;
  • file d'attente côté modèle amont, premier octet très lent.

Privilégiez le streaming ; fixez un délai raisonnable par requête ; découpez les tâches longues en phases ; réduisez le périmètre des outils approuvés automatiquement ; changez de réseau ou utilisez un partage mobile pour identifier rapidement un problème local. L'interception TLS d'entreprise exige de faire truster l'autorité de certification par VS Code et le système ; les clients Node doivent parfois configurer NODE_EXTRA_CA_CERTS.

7. Journaux et support : décrire le problème clairement

N'envoyez pas seulement « ça plante ». Rassemblez les informations suivantes :

  1. Heure, fuseau horaire et durée de l'incident.
  2. Version de Roo Code, version de VS Code et système d'exploitation.
  3. Type de fournisseur, Base URL (domaine seul) et identifiant du modèle.
  4. Streaming ou non, durée de la requête et nombre de tentatives.
  5. Statut HTTP, type d'erreur et message complet.
  6. request-id, présent éventuellement dans les en-têtes et le corps.
  7. Périmètre : une machine, un projet, un réseau ou toute l'équipe.
  8. Reproduction minimale : une commande curl ou un dépôt minimal, et le résultat de la même requête sur l'entrée du fournisseur.

Emplacement des journaux : dans le panneau Output de VS Code, cherchez le canal Roo Code ; les erreurs de l'hôte d'extension et des outils MCP peuvent apparaître dans la console des Developer Tools ; pour un problème de passerelle, transmettez le request-id au support. Après l'archivage du dépôt principal, les issues GitHub peuvent être en lecture seule : vérifiez d'abord le canal de support de la branche communautaire utilisée. Anonymisez précisément : ne gardez que les quatre premiers et quatre derniers caractères de la clé, et traitez prompts et code selon les règles de l'entreprise.

8. Exemple : décider du retry selon le type d'erreur

L'exemple ci-dessous utilise une interface compatible OpenAI : 401 et 404 échouent immédiatement ; 429, 5xx et délais sont réessayés avec backoff. Il sert à la fois de script autonome pour reproduire un problème et de base pour vos traitements par lots.

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 : vérifier fournisseur, clé et en-tête, request-id={exc.request_id}") from exc
        except NotFoundError as exc:
            raise SystemExit(f"404 : vérifier Base URL et identifiant de modèle, request-id={exc.request_id}") from exc
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429 : nouvelle tentative dans {wait:.1f}s")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            wait = min(2 ** attempt, 10) + random.random()
            print(f"Délai ou connexion échouée : nouvelle tentative dans {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code} : nouvelle tentative dans {wait:.1f}s")
                time.sleep(wait)
                continue
            raise

    raise RuntimeError("Nombre de tentatives épuisé, passer en dégradé ou alerter")

print(ask("Réponds seulement OK"))

L'exemple ne fixe pas explicitement le nombre de retries du SDK ; en production, configurez ensemble les retries par défaut du SDK et ceux de l'application. La Base URL est généralement https://ai.zhongshangqihang.com/v1, et l'identifiant du modèle se copie depuis la page tarifs des modèles.

Questions fréquentes

Un 401 signifie-t-il toujours une clé erronée ?

Non. Un type de fournisseur incompatible, une Base URL pointant vers le mauvais environnement ou un proxy réécrivant l'en-tête d'authentification produisent aussi un 401. Testez d'abord en direct avec la même clé et la même Base URL, puis vérifiez le fournisseur et le profil dans Roo Code.

Le 404 indique model not found : comment confirmer l'identifiant ?

Appelez /v1/models pour obtenir la liste visible par la clé, copiez l'identifiant exact sans le saisir de mémoire. Vérifiez ensuite que la Base URL ne duplique pas le chemin et que le protocole du fournisseur correspond.

Un 429 se rétablit-il toujours après une attente ?

Pas nécessairement. Une limitation de fréquence se rétablit généralement ; un 429 déclenché par le quota ou le solde peut ne pas contenir de retry-after, et attendre ne sert à rien : il faut ajuster la limite ou recharger. Regardez le type d'erreur et les en-têtes avant de décider.

Un dépassement de contexte est-il un problème de modèle ?

Généralement non. C'est le budget entrée plus sortie qui dépasse la fenêtre, ou la fenêtre configurée dans Roo Code qui dépasse la valeur réelle du modèle. Réduire l'entrée, activer la compression et découper les tâches est plus direct que changer de modèle.

Un flux qui renvoie 200 puis s'interrompt est-il un succès ?

Non. Une réponse en flux peut envoyer un événement d'erreur après le 200. Le client doit analyser le flux et confirmer la fin normale ; sinon, marquez le résultat comme incomplet et réessayez ou alertez.

Étape suivante

Créez d'abord une clé de test sur la passerelle ZSQH AI, puis exercez successivement 401, 404, 429 et le délai avec la commande curl et le script ci-dessus avant de brancher la supervision de production. Disponibilité des modèles et facturation font foi sur la page tarifs des modèles.

Lecture associée :

Note : Roo Code, Cline, Cursor, Claude Code, Anthropic, OpenAI et les autres noms sont des marques ou marques déposées de leurs titulaires respectifs. Cet article n'a qu'une visée de diagnostic technique et n'implique aucune affiliation ni coopération avec ces sociétés. Les types d'erreur et le comportement du client évoluent avec les versions : référez-vous à la documentation officielle et aux annonces du dépôt.