toncenter 429 : corriger l'erreur « Too Many Requests »

Un agent qui gère des tokens sur TON plante au pire moment : l'utilisateur demande « montre-moi mon solde et mes dernières transactions », l'agent part consciencieusement interroger toncenter — et au lieu d'un JSON avec les données, il reçoit un laconique HTTP 429 Too Many Requests. En un seul tick, l'agent a essayé de récupérer le solde du portefeuille, l'état du compte, l'historique des transactions et d'appeler deux ou trois get-methods — et le toncenter public lui a claqué la porte au nez dès la deuxième requête. L'utilisateur voit « une erreur est survenue », et vous, un mur de logs rouges avec toujours le même statut. Ce n'est pas un bug de votre code. C'est la limite de débit publique de toncenter, contre laquelle bute n'importe quel agent dès qu'il dépasse une requête par seconde.

Voyons d'où vient ce toncenter 429, pourquoi ce sont précisément les agents IA qui se prennent le plus de Too Many Requests sur TON, comment faire chuter rapidement la fréquence des erreurs avec un backoff — et comment supprimer complètement le plafond en passant sur votre propre clé, avec un débit garanti.

Ce que signifie le 429 « Too Many Requests » sur toncenter

Le code 429 est la réponse HTTP standard « trop de requêtes ». Le serveur n'est pas cassé et n'a pas rejeté vos données : il vous dit simplement que vous avez dépassé la fréquence d'appels autorisée et qu'il vous freine (rate limiting). Chez toncenter (v2), le corps de la réponse ressemble à peu près à ceci :

{ "ok": false, "error": "Rate limit exceeded", "code": 429 }

L'essentiel : "ok": false et "code": 429 — c'est le statut HTTP recopié dans le corps, pas un code d'erreur interne du contrat. Et remarquez bien : il n'y a ici aucun champ result avec les données du compte — le texte de la limite se trouve dans le champ error. Du coup, si votre code s'attend à extraire les données de result, il récupérera undefined et plantera très probablement plus loin dans la pile, sur une obscure erreur de parsing — alors que la vraie cause est dans error. La règle est simple : quand ok: false, commencez par vérifier code et lire error, au lieu de disséquer un result qui n'existe pas.

Petite parenthèse folklorique : dans la communauté TON circule une « erreur 228 ». Ce n'est pas un code d'API, c'est un mème — aucun serveur ne vous renverra jamais 228. Le vrai code de limite, c'est bien 429, et c'est celui-là qu'il faut chercher dans la documentation. Le 429 est une erreur temporaire : le même appel passera si vous le faites plus lentement ou avec une clé valide.

Pourquoi toncenter donne ~1 requête/s sans clé

Le toncenter public, sans clé d'API, vous limite à environ une requête par seconde. Ce n'est ni un bug ni de l'avarice — c'est la protection d'une ressource gratuite mutualisée qu'utilisent des milliers de personnes en même temps. Deux subtilités qui font trébucher même les développeurs expérimentés :

• Le pool commun, c'est le trafic anonyme. Sans clé, vous partagez une limite publique unique d'environ 1 rps avec toutes les requêtes anonymes du monde entier. Aux heures de pointe, la fréquence réellement disponible peut même descendre plus bas.
• Une clé payante relève le plafond — mais uniquement si elle est effectivement transmise dans la requête. Le piège classique : la clé existe, mais l'en-tête X-API-Key s'est perdu lors d'un refactoring du client HTTP, et vous voilà de nouveau sur la limite publique, à vous demander pendant des heures pourquoi votre offre payante « ne marche pas ».

Une requête par seconde, c'est parfait pour du débogage manuel dans le navigateur ou pour un script qui vérifie un solde une fois par minute. Pour la moindre automatisation, et a fortiori pour un agent, c'est dramatiquement insuffisant.

Pourquoi les agents IA se prennent le plus de 429 : le pattern en rafales

C'est là que le bât blesse. Une application classique envoie ses requêtes de façon plus ou moins régulière. Un agent IA, lui, fonctionne autrement — par rafales (burst). Il travaille par ticks : à chaque étape de raisonnement, il doit rassembler du contexte, et il enchaîne des dizaines d'appels d'affilée, presque simultanément.

Imaginez une seule étape : « l'utilisateur demande de vérifier si le paiement est bien arrivé ». Pour répondre, l'agent enchaîne en une fraction de seconde :

1. get_masterchain_info — connaître la tête actuelle de la blockchain ;
2. get_balance — le solde du portefeuille ;
3. get_account_state — le statut et les flags du compte ;
4. get_transactions — les dernières transactions ;
5. run_get_method — lire un get-method du contrat ;
6. get_jetton_balance — et tant qu'à faire, le solde USDT.

Six appels en un seul tick. La limite : un par seconde. Le premier passera, les autres renverront 429, et l'agent va soit se bloquer, soit se mettre à halluciner sur des données incomplètes. Et ce n'est pas un « agent mal fichu » — c'est l'architecture normale d'un raisonnement autonome : rassembler le contexte, puis réfléchir. Pire encore : une fois les erreurs récoltées, l'agent tente souvent de les « réparer » par de nouveaux appels — et achève un quota déjà épuisé. La limite publique n'est tout simplement pas dimensionnée pour ce profil de charge.

Même histoire du côté des liteservers publics de la configuration globale de TON — sous charge, ils répondent not ready ou tombent en timeout ADNL. Sujet traité à part : pourquoi le liteserver répond « not ready » et que faire. Et tonapi.io souffre du même mal du 429 — l'analyse est ici.

Le fix rapide : retries avec backoff exponentiel et Retry-After

La première chose à faire dès maintenant, c'est d'arrêter de foncer dans le mur à pleine vitesse. Si le 429 tombe quand même, ne martelez pas le serveur dans la foulée : cela ne fait que prolonger la punition. C'est un palliatif — il réduit la fréquence des 429, mais ne relève pas le plafond. Un bon palliatif tient en quatre points.

1. Backoff exponentiel avec jitter. Attendez plus longtemps à chaque nouvelle tentative, plus un supplément aléatoire, pour que vos workers parallèles ne se synchronisent pas et ne frappent pas tous à la même seconde.

async function fetchWithBackoff(url, opts = {}, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, opts);
    if (res.status !== 429) return res;

    // Priorité au Retry-After du serveur, sinon exponentielle avec jitter
    const retryAfter = res.headers.get("Retry-After");
    const baseMs = retryAfter
      ? Number(retryAfter) * 1000
      : Math.min(1000 * 2 ** attempt, 16000);
    const jitter = Math.random() * 300;
    await new Promise((r) => setTimeout(r, baseMs + jitter));
  }
  throw new Error("toncenter : le 429 n'a pas lâché après les retries");
}

2. Respectez l'en-tête Retry-After s'il arrive. toncenter ne l'envoie généralement pas avec ses 429, misez donc surtout sur votre propre formule de backoff. Mais si le serveur a tout de même indiqué combien de temps attendre — attendez exactement ce temps-là au lieu de deviner (c'est précisément ce que fait la branche if (retryAfter) dans le code ci-dessus).

3. Limitez la concurrence. Placez devant toncenter une file d'attente ou un sémaphore qui ne laisse passer qu'environ 1 requête par seconde. La rafale de l'agent s'étale alors dans le temps : la fameuse liste de six appels s'exécutera séquentiellement, en ~6 secondes, mais sans un seul 429.

4. Mettez en cache les lectures répétées. get_masterchain_info peut être demandé une seule fois par étape, puis réutilisé. Les métadonnées d'un jetton (decimals, symbole) ne changent pas — lisez-les une fois pour toutes. Un solde que vous avez lu il y a 300 ms n'a probablement pas bougé.

Ça fonctionne, et ça rend votre agent plus poli, mais soyons honnêtes : le backoff ne relève pas le plafond. Vous êtes toujours enfermé dans 1 rps, sauf que maintenant vous faites poliment la queue au lieu de planter. L'utilisateur attend des secondes là où il pourrait attendre des millisecondes. Pour un agent qui a besoin de réactivité, c'est soigner le symptôme, pas la maladie. D'autres contournements des API publiques dans notre sélection d'alternatives à toncenter pour 2026.

La vraie solution : votre propre clé et TON via MCP

La racine du problème, c'est que vous partagez un canal public étroit avec des milliers de requêtes anonymes. Le seul moyen de supprimer vraiment les 429, c'est d'obtenir votre propre débit garanti au lieu d'un quota mutualisé. La rafale de six appels de l'agent passe alors en entier, au lieu de buter contre le mur au cinquième, et l'agent peut rassembler son contexte à pleine vitesse. Les retries avec backoff restent comme filet de sécurité contre les incidents réseau, mais cessent d'être votre principal mécanisme de survie.

Et il existe une voie qui, en prime, supprime toute la bidouille autour des statuts HTTP. Si les données de TON sont destinées précisément à un agent IA, il est plus logique de les lui livrer non pas sous forme de réponse REST brute qu'il faut parser et traiter en cas de 429, mais comme des outils prêts à l'emploi via MCP.

MCP (Model Context Protocol) est le standard par lequel les agents IA (Claude, Cursor, ChatGPT/Codex, n'importe quel client MCP) appellent des outils externes. Au lieu d'apprendre à l'agent à former correctement une requête HTTP vers toncenter, à attraper les 429, à lire Retry-After et à parser du JSON, vous lui donnez des outils typés, et le serveur se charge de tout le sale boulot réseau.

TONNode est un serveur MCP hébergé pour TON, avec exactement 16 outils. Les six lectures avec lesquelles l'agent fait habituellement sauter la limite de toncenter sont ici des appels prêts à l'emploi :

• get_masterchain_info — la tête du masterchain ;
• get_balance — le solde GRAM ;
• get_account_state — statut, flags, dernière transaction ;
• get_transactions — l'historique des transactions ;
• run_get_method — n'importe quel get-method read-only d'un contrat ;
• get_jetton_balance — le solde d'un jetton ou d'USDT (l'adresse du jetton wallet est calculée on-chain).

(Au passage, GRAM est le Toncoin renommé en juin 2026. Le réseau s'appelle toujours TON, seul le nom de la monnaie a changé.)

Sous le capot, le paquet @tonnode/mcp fonctionne via le protocole natif de TON — ADNL, sans couche HTTP. Autrement dit, vous ne remplacez pas simplement un endpoint REST par un autre : l'agent parle directement au réseau, et vous cessez de démêler à la main la sémantique HTTP des limites. Le paquet est open source (MIT), publié sur npm et GitHub (tonnode/mcp).

La différence en pratique : l'agent n'a plus besoin de savoir ce qu'est un 429, un Retry-After ou un timeout ADNL. Il dit « donne-moi le solde et les dernières transactions de cette adresse » — et reçoit une réponse structurée. La même rafale de six appels part vers un serveur qui dispose d'un débit dédié sous votre clé, et non vers la limite publique commune.

Comment se connecter et démarrer gratuitement

Il y a deux voies, et vous pouvez commencer sans même créer de compte.

Gratuit et en local

L'ensemble complet des outils de lecture via la configuration publique — ajoutez simplement ceci aux réglages de votre client MCP :

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Aucune clé, npx récupère le paquet tout seul. C'est amplement suffisant pour essayer et constater que votre agent lit TON sans un seul 429. Analyse détaillée dans le guide du MCP gratuit pour TON.

Endpoint hébergé avec votre propre clé

Quand il vous faut un débit garanti pour une charge réelle, vous branchez l'endpoint hébergé avec votre clé :

{
  "mcpServers": {
    "ton": {
      "type": "http",
      "url": "https://mcp.tonnode.io/mcp",
      "headers": { "Authorization": "Bearer tn_live_…" }
    }
  }
}

Ensuite, il suffit de parler à l'agent en langage naturel — il choisira lui-même le bon outil :

« Vérifie l'adresse EQC… : récupère le solde via get_balance, l'état du compte via get_account_state et les 10 dernières transactions via get_transactions. Ensuite, regarde le solde USDT via get_jetton_balance. »

L'agent appellera les bons outils dans le bon ordre — au lieu de se cogner à l'aveugle contre la limite de débit.

Tarifs

Sur toutes les offres, les 16 outils sont disponibles — vous ne payez que le débit :

Offre	Prix	Débit
Hobby	gratuit pour toujours	60 requêtes/min
Pro	29 $/mois	300 requêtes/min
Scale	199 $/mois	1200 requêtes/min

Même l'offre gratuite Hobby, avec ses 60 requêtes/min, joue dans une tout autre catégorie que le toncenter public et son ~1 rps : les mêmes ~60 requêtes par minute, mais cette fois garanties et rien qu'à vous, au lieu d'être partagées avec une foule d'anonymes. Une rafale d'une dizaine d'appels passe en entier, sans un seul 429. La clé Hobby est délivrée dès la connexion, sans carte bancaire.

Le paiement des offres payantes se fait en GRAM ou en USDT sur le réseau TON via TonConnect, ou bien en BTC/ETH/SOL et autres via un compte xRocket dans Telegram.

Deux mises au point honnêtes, pour éviter les attentes démesurées : TONNode couvre aujourd'hui la lecture et la construction de transactions, mais ne propose pas, en tant que produits finis, de pay-per-request, d'API REST v2, de webhooks, de flux SSE ni de SLA écrit avec pourcentages d'uptime. Le nœud d'archive à historique profond est encore en cours de synchronisation — c'est un point de roadmap, pas une garantie d'aujourd'hui. Tout ce qui est décrit ci-dessus fonctionne déjà.

Un plan de migration concret

1. Récupérez la clé Hobby gratuite (60 requêtes/min, sans carte bancaire) : tonnode.io/dashboard?plan=hobby.
2. Ajoutez la configuration hébergée ci-dessus dans votre client MCP.
3. Remplacez vos appels manuels à toncenter par les outils get_balance, get_account_state, get_transactions, run_get_method, get_jetton_balance.
4. Dès que votre agent butera sur les 60 requêtes/min en charge — passez à Pro à 29 $/mois (300 requêtes/min) : tonnode.io/pricing.

En résumé

• Le 429 « Too Many Requests » sur toncenter, c'est le plafond public d'environ 1 rps, pas une panne de votre code. (Et ce n'est certainement pas le « 228 » — ce code n'existe pas.)
• Les agents IA se le prennent plus souvent que tout le monde à cause du pattern en rafales : des dizaines d'appels en un seul tick de raisonnement.
• Les retries avec backoff exponentiel, Retry-After, un sémaphore et du cache réduisent la fréquence des 429, mais ne déplacent pas le plafond — et cela au prix de la vitesse.
• La vraie issue, c'est votre propre clé avec un débit garanti. Et si les données sont destinées à un agent, TONNode livre ces mêmes lectures TON sous forme d'outils MCP, et la question « comment gérer le 429 » disparaît tout simplement de votre code.

Commencez gratuitement : obtenir une clé Hobby — 60 requêtes/min, sans carte bancaire. Si votre agent tourne en charge réelle avec des rafales denses — prenez directement Pro à 29 $/mois, 300 requêtes/min.