OpenCode Free Limit Reached : attendre, changer ou continuer

Lorsque OpenCode affiche Free limit reached ou HTTP 429, ne supposez pas que tous les modèles gratuits se réinitialisent chaque jour à une heure fixe. Conservez l’erreur d’origine, confirmez le provider et le model actifs, puis utilisez uniquement une indication de reset réellement présente dans la réponse ou le compte actuel.

S’il n’existe aucune heure fiable, vous pouvez attendre, sélectionner un autre modèle actuellement visible dans /models, ou passer explicitement à un provider facturé séparément. Avant de relancer une longue tâche, envoyez une petite requête sans modification de fichiers et vérifiez la réponse, le provider/model sélectionné et l’usage enregistré côté provider.

Choisir la bonne branche à partir du symptôme

Ce qui s’affiche	Branche probable	Première action
Free limit reached ou FreeUsageLimitError, sans compte à rebours	Limite de l’offre gratuite	Ne pas inventer de cycle ; noter l’heure, attendre ou consulter les modèles actuels dans /models
Go limit reached avec un vrai compte à rebours	Fenêtre d’usage payante d’OpenCode Go	Suivre l’heure affichée pour ce compte, sans l’appliquer aux modèles gratuits
429, Too Many Requests ou Provider is overloaded générique	Rate limit, manque de capacité ou incident temporaire du provider	Garder la réponse complète, confirmer provider/model, réessayer plus tard et consulter son statut
401, 404 ou Model not available	Problème d’authentification, de Base URL ou de Model ID	Ne pas attendre un reset ; corriger les identifiants, l’endpoint ou la configuration du modèle

Un même statut HTTP peut avoir plusieurs causes. Un 429 peut correspondre à une limite gratuite, à un rate limit ordinaire du provider ou à une surcharge temporaire. Le code seul ne justifie donc ni l’achat d’un abonnement ni la réécriture complète de la configuration.

Enregistrer quatre éléments avant tout changement

1. Le texte complet de l’erreur, pas seulement « 429 ».
2. Le provider et le model sélectionnés, si possible sous la forme providerId/modelId.
3. Le response body, le type d’erreur, les headers et la valeur retry-after visibles, si le client les expose réellement.
4. L’heure et le fuseau du problème, le répertoire du projet et le chemin utilisé : Zen gratuit, Go ou custom provider.

Selon la documentation OpenCode Zen, exécutez /models dans la TUI pour vérifier l’entrée sélectionnée et les modèles listés maintenant. Vous pouvez aussi lancer opencode models dans un terminal. Ne concluez pas qu’un modèle gratuit est toujours disponible à partir d’une ancienne capture ou d’un ancien tutoriel : la liste peut évoluer.

Vérifiez également la priorité des configurations. La documentation de configuration OpenCode précise qu’OpenCode fusionne plusieurs sources, et un opencode.json au niveau du projet peut remplacer les réglages globaux. Avoir choisi le modèle A globalement ne prouve pas que le dépôt courant l’utilise. Fiez-vous au projet actif, à la sélection dans /models et à la configuration résolue.

Ne croire qu’un reset réellement affiché

Si l’erreur actuelle ne contient ni compte à rebours fiable ni heure absolue, n’en déduisez pas « dans quelques heures », « demain » ou « la semaine prochaine ».

Dans le snapshot de retry.ts de la branche dev d’OpenCode ouvert et vérifié le 2026-10-10, FreeUsageLimitError passe par une branche statique d’avertissement de limite gratuite. GoUsageLimitError, en revanche, lit le header retry-after et forme un compte à rebours. Il s’agit d’une vérification de code source, pas d’un test d’exécution de votre version installée ou de votre compte.

Les feature requests #53252 et #52894 ont montré des heures de reset à titre d’exemple, mais ces chiffres illustrent la fonctionnalité demandée ; ils ne constituent pas un calendrier observé de l’offre gratuite. La fermeture d’un issue ne prouve pas non plus que le changement est présent dans votre version du client.

La documentation OpenCode Go, ouverte le 2026-10-10, définit séparément des fenêtres de 5 heures, hebdomadaires et mensuelles pour l’usage payant. Ces règles Go ne permettent pas d’inférer le reset des modèles gratuits.

Appliquez cette règle :

• Un compte à rebours ou une heure exacte apparaît : enregistrez le texte, le fuseau et le provider, puis faites une seule tentative près de cette heure.
• Aucune heure n’apparaît : considérez le reset comme inconnu, évitez les essais rapides répétés et ne remplacez pas l’information par la fenêtre d’un autre plan.
• Seul un 429 générique apparaît : examinez le throttling ou la surcharge du provider jusqu’à ce que les éléments identifient réellement une limite gratuite.

Option 1 : attendre si vous avez besoin du même modèle gratuit

L’attente est le choix le plus simple si la tâche n’est pas urgente, si vous ne voulez pas générer de consommation sur une autre API et si l’erreur pointe clairement vers la couche gratuite.

1. Notez l’heure du dernier échec et l’erreur brute.
2. Arrêtez les tentatives en boucle pour ne pas confondre quota et rate limit transitoire.
3. Si un minuteur fiable existe, réessayez près de l’heure indiquée. Sans minuteur, vérifiez après un intervalle acceptable sans annoncer de cycle fixe.
4. Testez d’abord une requête courte, pas une tâche qui lit ou modifie beaucoup de fichiers.

Le succès n’est pas « OpenCode se lance » ni « le processus renvoie exit code 0 ». Le modèle choisi doit produire une vraie réponse sans répéter immédiatement l’erreur initiale.

Option 2 : sélectionner un autre modèle présent dans /models

Si vous devez continuer sans exiger le modèle d’origine, choisissez une autre entrée visible maintenant pour votre compte et accessible via le provider prévu.

Avant de changer, vérifiez que :

• le modèle figure dans la liste actuelle et pas seulement dans un ancien guide ;
• l’entrée appartient au provider attendu, afin qu’un changement de modèle ne devienne pas silencieusement un changement de compte ou de facturation ;
• le modèle convient à la tâche : testez d’abord une petite demande de compréhension de code ou de tool use avant de l’autoriser à modifier le dépôt.

Changer de modèle n’est pas une garantie. Un autre modèle gratuit peut avoir sa propre limite, une restriction régionale, un retrait temporaire ou un problème de capacité. La consigne défendable est « choisir un modèle actuellement disponible et le vérifier », pas « changer de modèle gratuit fonctionne toujours ».

Option 3 : utiliser explicitement un provider facturé séparément

Cette voie convient si vous avez une échéance, acceptez une consommation API distincte et voulez que les prochaines requêtes ne dépendent plus de la quota gratuite Zen. Elle ne réinitialise pas la quota : les appels passent par un autre compte, une autre API Key et un autre registre d’usage.

La documentation OpenCode sur les providers confirme les custom OpenAI-compatible providers. Le flux minimal est le suivant :

1. Exécutez /connect, choisissez Other, saisissez un provider ID unique et enregistrez l’API Key dans le champ d’identification.
2. Configurez le même provider ID, le bon Base URL et le Model ID réel dans opencode.json, puis enregistrez le fichier.
3. Fermez complètement OpenCode et redémarrez-le dans le même projet avant de vérifier la nouvelle configuration ; ne supposez pas qu’une TUI déjà ouverte recharge à chaud un nouveau provider. Si vous devez conserver le contexte précédent, notez le répertoire du projet ainsi que la tâche ou session à retrouver, puis revenez-y en toute sécurité après le redémarrage avec le flux disponible dans votre environnement.
4. Après le redémarrage, exécutez /models, vérifiez que la nouvelle entrée apparaît et sélectionnez le providerId/modelId exact plutôt que le seul nom affiché.
5. Envoyez une petite requête qui interdit explicitement toute modification de fichier et confirmez la réception d’une nouvelle réponse réelle du modèle.
6. Consultez le journal de requêtes, le relevé d’usage ou la variation de solde du provider cible pour vérifier qu’il a bien traité cette requête. Sans enregistrement correspondant, n’affirmez pas que le changement est vérifié.

BetterToken est une option pour cette route indépendante. Sa documentation de configuration OpenCode, ouverte le 2026-10-10, indique le Base URL https://www.bettertoken.ai/v1 et une référence telle que bettertoken/YOUR_MODEL_ID. N’ajoutez pas /chat/completions au Base URL et assurez-vous que le champ supérieur model correspond exactement à l’ID réel déclaré dans models.

La limite doit rester claire : BetterToken ne fournit pas la quota gratuite Zen et ne réinitialise pas une limite OpenCode/Zen. Il ne garantit pas l’absence de tout 429 et n’est pas automatiquement moins cher sans comparaison à usage identique. C’est une route API séparée et explicite, pas un reset.

Vérifier la reprise avec une petite requête

Utilisez le même test après l’attente, un changement de modèle ou un changement de provider :

1. Confirmez de nouveau le provider/model sélectionné dans l’interface.
2. Demandez uniquement le mot READY en précisant de ne modifier aucun fichier.
3. Conservez la réponse et l’heure. Vérifiez qu’il s’agit d’une nouvelle réponse du modèle, pas seulement d’une confirmation de configuration ou d’une sortie en cache.
4. Avec un provider indépendant, cherchez la petite variation correspondante dans le relevé d’usage, le journal de requêtes ou le solde. S’il n’expose pas cet élément, n’affirmez pas que la facturation a été vérifiée.
5. Si l’erreur initiale ne revient pas, reprenez la vraie tâche par son plus petit élément utile.

Un PASS valide combine une vraie réponse, le provider/model attendu et une preuve d’usage côté provider. Une configuration analysée sans erreur, un client lancé ou un exit code propre ne suffisent pas séparément.

Si la petite requête échoue encore

Suivez la nouvelle erreur au lieu de répéter toutes les corrections :

• Le même Free limit reached revient : la quota n’est peut-être pas revenue ou la sélection n’a pas réellement changé. Revérifiez /models et la configuration du projet.
• Un 401 apparaît : vérifiez que le credential existe pour ce provider. Exécutez opencode auth list et recommencez /connect si nécessaire.
• Un 404 ou Model not available apparaît : contrôlez Base URL, Model ID et providerId/modelId, puis lancez opencode models pour connaître l’accès actuel.
• Un 429 générique ou une surcharge apparaît : traitez-le comme du throttling provider, réduisez la fréquence des essais et consultez son statut au lieu de continuer à l’attribuer à Zen.
• L’erreur est incomplète : utilisez le guide de dépannage OpenCode pour consulter les logs, puis fournissez l’heure, le provider, le model, le statut et un response body expurgé.

Ne collez jamais une API Key dans un issue, une capture ou un chat. Conservez les données utiles, mais retirez les Authorization headers, les tokens et les autres identifiants.

Questions fréquentes

La quota gratuite OpenCode se réinitialise-t-elle chaque jour à heure fixe ?

Aucune source primaire fiable ne permet d’affirmer que tous les modèles gratuits partagent un cycle quotidien, hebdomadaire ou mensuel unique. Utilisez l’heure de la requête actuelle ; si aucune heure n’apparaît, considérez-la comme inconnue.

Tout 429 signifie-t-il que la quota gratuite est épuisée ?

Non. Il peut aussi s’agir d’un rate limit ordinaire, d’une limite de concurrence ou d’une surcharge du provider. Interprétez-le avec provider, model, response body et type d’erreur.

S’abonner à OpenCode Go est-il le seul moyen de continuer ?

Non. Vous pouvez attendre, choisir un autre modèle actuellement disponible ou utiliser explicitement un provider indépendant. Go est un plan payant séparé ; ses fenêtres ne prouvent pas le reset de la couche gratuite.

Passer à BetterToken efface-t-il la limite gratuite ?

Non. C’est une route indépendante avec sa propre API Key, son Base URL, son Model ID et sa comptabilité d’usage. Elle ne change pas l’état de la quota gratuite Zen.

La règle pratique

Ne résolvez pas Free limit reached en devinant un cycle de reset. Identifiez le provider/model, fiez-vous uniquement à une heure réelle et choisissez la voie la moins perturbante selon l’échéance : attendre, sélectionner un modèle disponible dans /models ou utiliser un provider facturé séparément. Prouvez la reprise par une courte réponse et l’usage provider avant de revenir à la tâche d’origine.