toncenter 429 «Too Many Requests»: cómo eliminar el error

Tu agente de tokens en TON se cae en el peor momento posible: el usuario pide «muéstrame mi balance y las últimas operaciones», el agente va obedientemente a toncenter — y en lugar de un JSON con datos recibe un seco HTTP 429 Too Many Requests. En un solo tick el agente intentó reunir el balance del wallet, el estado de la cuenta, el historial de transacciones y llamar a un par de get-methods — y el toncenter público se le cerró en la segunda petición. El usuario ve un «algo salió mal», y tú, una pared de logs rojos con el mismo estado una y otra vez. No es un bug de tu código. Es el rate limit público de toncenter, contra el que choca cualquier agente en cuanto empieza a trabajar a más de una petición por segundo.

Veamos de dónde sale el toncenter 429, por qué son precisamente los agentes IA quienes más se topan con el Too Many Requests en TON, cómo bajar rápido la frecuencia de errores con backoff — y cómo quitar el techo del todo pasándote a una clave propia con throughput garantizado.

Qué significa el 429 «Too Many Requests» en toncenter

El código 429 es la respuesta HTTP estándar de «demasiadas peticiones». El servidor no se rompió ni rechazó tus datos: simplemente te está diciendo que superaste la frecuencia permitida y te está frenando (rate limiting). En toncenter (v2), el cuerpo de la respuesta se ve más o menos así:

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

Lo importante: "ok": false y "code": 429 — es el estado HTTP duplicado en el cuerpo, no un código interno de error del contrato. Y fíjate en un detalle: aquí ni siquiera aparece el campo result con los datos de la cuenta — el texto del límite viene en el campo error. Por eso, si tu código espera sacar los datos de result, recibirá undefined y lo más probable es que reviente más adelante en el stack con un error de parseo incomprensible — mientras la causa real estaba en error. La regla es simple: con ok: false, primero comprueba code y lee error, en vez de intentar parsear un result inexistente.

Un apunte de folclore: en la comunidad de TON circula el «error 228». No es un código de la API, es un meme — ningún servidor te va a devolver un 228. El código real del límite es 429, y es el que hay que buscar en la documentación. El 429 es un error temporal: la misma llamada pasará si la haces más despacio o con una clave válida.

Por qué toncenter sin clave da ~1 petición/s

El toncenter público sin API key te limita a aproximadamente una petición por segundo. No es un bug ni avaricia — es la protección de un recurso gratuito compartido que usan miles de personas a la vez. Un par de matices con los que tropiezan hasta desarrolladores con experiencia:

• El pool compartido lo comparte todo el tráfico anónimo. Sin clave, compartes un único límite público de ~1 rps con todas las peticiones anónimas del mundo entero. En hora punta, la frecuencia realmente disponible para ti puede ser incluso menor.
• La clave de pago sube el techo — pero solo si de verdad viaja en la petición. La trampa clásica: la clave existe, pero la cabecera X-API-Key se perdió en un refactor del cliente HTTP, y vuelves a estar en el límite público, pasando horas sin entender por qué el plan de pago «no funciona».

Una petición por segundo está bien para depurar a mano en el navegador o para un script que comprueba un balance una vez por minuto. Para cualquier automatización, y más aún para un agente, es ridículamente poco.

Por qué los agentes IA son los que más 429 reciben: el patrón de ráfagas

Aquí está el meollo del asunto. Una aplicación normal envía peticiones de forma más o menos uniforme. Un agente IA funciona distinto — a ráfagas (bursts). Trabaja por ticks: en un paso de razonamiento necesita reunir contexto, y lanza decenas de llamadas seguidas, casi simultáneas.

Imagina un solo paso: «el usuario pide comprobar si llegó un pago». Para responder, el agente dispara en fracciones de segundo, una tras otra:

1. get_masterchain_info — conocer la cabeza actual de la blockchain;
2. get_balance — el balance del wallet;
3. get_account_state — el estado y los flags de la cuenta;
4. get_transactions — las últimas transacciones;
5. run_get_method — leer un get-method del contrato;
6. get_jetton_balance — y de paso, el balance de USDT.

Seis llamadas en un tick. El límite: una por segundo. La primera pasa, el resto devuelve 429, y el agente o se queda atascado o empieza a alucinar a partir de datos incompletos. Y ojo, esto no es «un agente mal hecho» — es la arquitectura normal del razonamiento autónomo: reúne el contexto, luego piensa. Peor aún: al recibir los errores, el agente suele intentar «arreglarlos» repitiendo las llamadas — y remata una cuota ya agotada. El límite público simplemente no está pensado para ese perfil de carga.

Historia parecida con los liteservers públicos del config global de TON — bajo carga responden not ready o se caen por timeout de ADNL. De eso hablamos aparte: por qué el liteserver responde «not ready» y qué hacer. Y tonapi.io sufre la misma enfermedad del 429 — análisis aquí.

El fix rápido: reintentos con backoff exponencial y Retry-After

Lo primero que conviene hacer ahora mismo es dejar de estrellarte contra la pared a toda velocidad. Si aun así te llega un 429, no martillees el servidor de inmediato con otro intento: solo alarga el bloqueo. Esto es un paliativo — reduce la frecuencia de 429, pero no sube el techo. El paliativo bien hecho tiene cuatro partes.

1. Backoff exponencial con jitter. Haz que cada reintento espere más que el anterior, más un extra aleatorio para que los workers en paralelo no se sincronicen y golpeen todos en el mismo segundo.

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;

    // Prioridad: Retry-After del servidor; si no, exponencial con 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: el 429 no cedió tras los reintentos");
}

2. Respeta la cabecera Retry-After si llega. toncenter normalmente no la envía en el 429, así que apuesta principalmente por tu fórmula de backoff. Pero si el servidor sí indicó cuánto esperar, espera exactamente eso en vez de adivinar (en el código de arriba es justo lo que hace la rama if (retryAfter)).

3. Limita la concurrencia. Pon delante de toncenter una cola o un semáforo que no deje pasar más de ~1 petición por segundo. Así la ráfaga del agente se estira en el tiempo: aquella lista de seis llamadas se ejecuta en secuencia, en ~6 segundos, pero sin un solo 429.

4. Cachea las lecturas repetidas. Dentro de un mismo paso, get_masterchain_info lo puedes pedir una sola vez y reutilizar el resultado. Los metadatos de un jetton (decimals, símbolo) no cambian — léelos una sola vez. El balance que leíste hace 300 ms difícilmente habrá cambiado.

Funciona y hace al agente más educado, pero seamos honestos: el backoff no sube el techo. Sigues encerrado en 1 rps, solo que ahora haces cola educadamente en vez de caerte. El usuario espera segundos donde podría esperar milisegundos. Para un agente que necesita ser reactivo, esto trata el síntoma, no la enfermedad. Otras formas de sortear las APIs públicas están recopiladas en alternativas a toncenter para 2026.

La solución real: clave propia y TON vía MCP

La raíz del problema es que compartes un canal público estrecho con miles de peticiones anónimas. La única forma de eliminar el 429 de verdad es tener throughput propio y garantizado en lugar de una cuota compartida. Entonces la ráfaga de seis llamadas del agente pasa entera, en vez de estamparse contra la pared en la quinta, y el agente puede reunir contexto a toda velocidad. Los reintentos con backoff se quedan como seguro contra fallos de red, pero dejan de ser el mecanismo principal de supervivencia.

Y hay un camino que, además, te ahorra por completo lidiar con los estados HTTP. Si los datos de TON los necesita precisamente un agente IA, es más lógico servírselos no como una respuesta REST cruda que hay que parsear y tratar en el 429, sino como herramientas listas vía MCP.

MCP (Model Context Protocol) es el estándar con el que los agentes IA (Claude, Cursor, ChatGPT/Codex, cualquier cliente MCP) invocan herramientas externas. En vez de enseñarle al agente a construir bien la petición HTTP a toncenter, capturar el 429, leer Retry-After y parsear JSON, le das herramientas tipadas, y todo el trabajo sucio de red lo asume el servidor.

TONNode es un servidor MCP hosted para TON, exactamente 16 herramientas. Las seis lecturas con las que el agente suele reventar el límite de toncenter aquí son llamadas listas:

• get_masterchain_info — la cabeza de la masterchain;
• get_balance — el balance en GRAM;
• get_account_state — estado, flags, última transacción;
• get_transactions — historial de transacciones;
• run_get_method — cualquier get-method read-only del contrato;
• get_jetton_balance — balance de un jetton o de USDT (la dirección del jetton wallet se calcula on-chain).

(Por cierto, GRAM es el Toncoin renombrado en junio de 2026. La red se sigue llamando TON; solo cambió el nombre de la moneda.)

Por debajo, el paquete @tonnode/mcp habla el protocolo nativo de TON — ADNL, sin capas HTTP intermedias. Es decir, no estás simplemente cambiando un endpoint REST por otro: el agente se comunica con la red directamente, y tú dejas de gestionar a mano la semántica HTTP de los límites. El paquete es open source (MIT) y está en npm y GitHub (tonnode/mcp).

La diferencia en la práctica: el agente ya no necesita saber qué es un 429, Retry-After o un timeout de ADNL. Dice «dame el balance y las últimas transacciones de esta dirección» — y recibe una respuesta estructurada. Esa misma ráfaga de seis llamadas va a un servidor que tiene throughput bajo tu clave, no al límite público compartido.

Cómo conectarlo y por dónde empezar gratis

Hay dos caminos, y se puede empezar sin registrarse siquiera.

Gratis y en local

El set completo de herramientas de lectura a través del config público — solo añade esto a los ajustes de tu cliente MCP:

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

Sin claves de ningún tipo; npx descarga el paquete solo. Con esto basta para probarlo y comprobar que el agente lee TON sin un solo 429. El análisis detallado, en la guía de MCP para TON gratis.

Endpoint hosted con tu propia clave

Cuando necesitas throughput garantizado para carga real, conectas el endpoint hosted con tu clave:

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

A partir de ahí, simplemente hablas con el agente en lenguaje humano — él mismo elegirá la herramienta adecuada:

«Comprueba la dirección EQC…: obtén el balance con get_balance, el estado de la cuenta con get_account_state y las últimas 10 transacciones con get_transactions. Después mira el balance de USDT con get_jetton_balance.»

El agente invocará las herramientas correctas en el orden correcto — en vez de golpearse a ciegas contra el rate limit.

Planes

En todos los planes están disponibles las 16 herramientas — solo pagas por el throughput:

Plan	Precio	Throughput
Hobby	gratis para siempre	60 peticiones/min
Pro	$29/mes	300 peticiones/min
Scale	$199/mes	1200 peticiones/min

Incluso el Hobby gratuito con sus 60 peticiones/min juega en otra liga que el toncenter público con su ~1 rps: son unas ~60 peticiones por minuto, sí, pero garantizadas y tuyas, no compartidas con una multitud de anónimos. Una ráfaga del agente de una decena de llamadas pasa entera, sin un solo 429. La clave Hobby se entrega nada más iniciar sesión, sin tarjeta.

Los planes de pago se pueden abonar en GRAM o USDT en la red TON vía TonConnect, o en BTC/ETH/SOL y otras monedas mediante una factura de xRocket en Telegram.

Un par de aclaraciones honestas para no inflar expectativas: TONNode hoy cubre las tareas de lectura y construcción de transacciones, pero no ofrece como productos terminados pay-per-request, REST-API v2, webhooks, streams SSE ni un SLA por escrito con porcentajes de uptime. El nodo de archivo con historial profundo aún se está sincronizando — es un punto del roadmap, no una garantía de hoy. Todo lo descrito arriba funciona ya.

Plan de migración práctico

1. Consigue la clave Hobby gratuita (60 peticiones/min, sin tarjeta): tonnode.io/dashboard?plan=hobby.
2. Añade el config hosted de arriba a tu cliente MCP.
3. Sustituye las llamadas manuales a toncenter por las herramientas get_balance, get_account_state, get_transactions, run_get_method, get_jetton_balance.
4. En cuanto el agente choque con las 60 peticiones/min bajo carga — pásate a Pro por $29/mes (300 peticiones/min): tonnode.io/pricing.

En resumen

• El 429 «Too Many Requests» en toncenter es el choque contra el límite público de ~1 rps, no un fallo de tu código. (Y desde luego no es el «228» — ese código no existe.)
• Los agentes IA lo reciben más que nadie por el patrón de ráfagas: decenas de llamadas en un solo tick de razonamiento.
• Los reintentos con backoff exponencial, Retry-After, un semáforo y caché reducen la frecuencia de 429, pero no mueven el techo — y lo pagas en velocidad.
• La salida real es una clave propia con throughput garantizado. Y si los datos los necesita precisamente un agente, TONNode sirve esas mismas lecturas de TON como herramientas MCP, y la pregunta «cómo manejar el 429» simplemente desaparece de tu código.

Empieza gratis: consigue la clave Hobby — 60 peticiones/min, sin tarjeta. Si tu agente tiene carga real y ráfagas densas — ve directo al Pro por $29/mes, 300 peticiones/min.