Gestion des erreurs 429

Ce qui se passe, dans l'ordre

1. La requête part vers le serveur (/chat/completions).
2. Si le serveur répond 429, CsAgent lit le texte de la réponse pour savoir de quelle limite il s'agit (voir la section suivante).
3. Limite par minute ou non reconnue : CsAgent attend, puis renvoie la même requête, jusqu'au nombre maximal de tentatives.
4. Limite journalière : aucune nouvelle tentative, car attendre ne servirait à rien. CsAgent passe à un autre modèle si c'est possible, sinon il s'arrête avec un message.
5. Toute autre erreur HTTP (401, 500…) n'est jamais réessayée : elle est affichée tout de suite.

Reconnaître le type de limite

CsAgent cherche des mots dans le corps de la réponse 429, sans tenir compte des majuscules.

Si les deux familles de mots apparaissent, la limite journalière l'emporte. Exemple de réponse d'Albert : {"detail":"1280000 input tokens per day exceeded (remaining: 0)."}

Le délai entre deux essais

• Si le serveur envoie l'en-tête Retry-After (en secondes ou sous forme de date), CsAgent attend ce délai.
• Sinon, le délai double à chaque essai : délai de base × 2^(essai − 1).
• Dans les deux cas, l'attente est plafonnée à 70 secondes.

Avec les valeurs par défaut (6 tentatives, 1 000 ms de délai de base), il y a cinq attentes : 1, 2, 4, 8 et 16 secondes, soit environ 31 secondes au total avant d'abandonner.

Réglages en ligne de commande

Ces deux options valent pour tous les modes : terminal, interface web, Lean UI et mode --api.

• Une valeur absente, non numérique, nulle ou négative est ignorée sans message : la valeur par défaut s'applique.
• --retry-delay ne peut pas dépasser 70 000 (le plafond). Au-delà, la combinaison est refusée.
• Le facteur de doublement (2) et le plafond (70 s) ne se règlent pas en ligne de commande.

Durées d'attente cumulées

Quand le serveur envoie Retry-After, c'est lui qui fixe chaque attente, toujours dans la limite de 70 s.

Quota journalier épuisé : la bascule de modèle

Quand la limite est journalière, CsAgent ne perd pas la requête : il la renvoie à un autre modèle et poursuit la tâche, avec un message d'avertissement.

Quel modèle est choisi

1. Celui de la variable d'environnement CSAGENT_FALLBACK_MODEL, si elle est définie.
2. Sinon, le modèle de code (deepseek-v4-flash par défaut, ou la valeur de --code-model), uniquement sur l'endpoint Albert par défaut. Sur un autre --endpoint, ce nom ne veut rien dire : il n'y a alors pas de bascule automatique.

Règles de sécurité

• Au plus 2 bascules par exécution.
• Pas de bascule si la conversation contient une image : l'autre modèle ne saurait peut-être pas la lire.
• Pas de bascule vers le modèle qu'on quitte, ni vers un modèle lui aussi épuisé.
• Un modèle épuisé est mémorisé 1 heure, en mémoire du processus. Pendant ce temps, les messages suivants partent directement vers l'autre modèle, sans retenter le premier. Un redémarrage de CsAgent efface cette mémoire.

Il n'existe pas d'option en ligne de commande pour la bascule : seule la variable d'environnement la règle. Les options --model, --code-model, --chat-model et --endpoint fixent les modèles utilisés et, par ce biais, influencent la bascule.

set CSAGENT_FALLBACK_MODEL=openweight-large
csagent --max-retries 4

set CSAGENT_FALLBACK_MODEL=off
csagent

Quand tout échoue

CsAgent affiche API error: API 429: … suivi d'un conseil, puis arrête la tâche.

• Quota journalier épuisé : « The daily token quota is used up: retrying is useless until it resets. Wait for the reset, or use another model (--model) or endpoint (--endpoint). »
• 429 qui persiste après toutes les tentatives : « The API still answers 429 (rate limit) after the retries. Wait a little and try again, or send less text per request. »

Les messages peuvent apparaître traduits selon la langue.

Que faire selon la situation

Limites actuelles

• Pas d'affichage pendant l'attente : l'interface peut sembler figée jusqu'à 70 secondes sans message.
• Pas de comptage préventif : CsAgent ne sait pas qu'il approche de la limite, il la découvre par un refus.
• Limite mal identifiée : un 429 journalier dont le texte ne contient aucun des mots reconnus est traité comme une limite par minute. Il est alors réessayé jusqu'au bout avant l'échec.
• Options ignorées en silence : une valeur invalide pour --max-retries ou --retry-delay retombe sur le défaut sans avertissement.