Errores 429 de Polygon RPC y Límites de Tasa: Causas, Diagnóstico y Soluciones

Respuesta Directa: ¿Qué Significa un Error 429 de Polygon RPC?

Un error 429 de Polygon RPC (HTTP 429 Too Many Requests) significa que tu cliente ha excedido el límite de tasa impuesto por el endpoint RPC que estás utilizando. Este es un código de estado HTTP estándar que indica que el servidor está limitando las solicitudes para proteger su infraestructura. En Polygon (PoS), esto ocurre típicamente cuando envías demasiadas solicitudes por segundo o consumes demasiadas unidades de cómputo (por ejemplo, llamadas eth_getLogs costosas) en un período corto.

La solución no es aumentar el límite (que no puedes controlar en endpoints públicos) sino reducir tu tasa de solicitudes y optimizar tus patrones de consulta. Este artículo explica los mecanismos subyacentes, cómo diagnosticar la causa exacta y proporciona ejemplos de código ejecutables para implementar soluciones robustas.

Cómo Funciona la Limitación de Tasa de Polygon RPC

Polygon PoS expone una API JSON-RPC compatible con Ethereum. Los endpoints públicos (como los listados en la documentación oficial de Polygon) y los proveedores comerciales (como OnFinality) aplican límites de tasa para garantizar un uso justo y prevenir denegaciones de servicio. Estos límites se basan típicamente en dos factores: solicitudes por segundo (RPS) y unidades de cómputo (CU). Las unidades de cómputo son una medida del costo computacional de una solicitud; por ejemplo, eth_getLogs con un rango de bloques amplio es mucho más costoso que eth_getBalance para una sola dirección.

Cuando excedes estos límites, el servidor responde con HTTP 429 y a menudo incluye un encabezado Retry-After que indica cuántos segundos esperar antes de reintentar. Algunos proveedores también pueden devolver un error JSON-RPC con código -32005 (límite excedido) en lugar de un HTTP 429 puro, por lo que es importante manejar ambos casos.

Es crucial tener en cuenta que los valores exactos de los límites de tasa y los algoritmos son específicos de la implementación. Los endpoints públicos pueden tener límites más estrictos que los proveedores comerciales. Por ejemplo, la página de red de Polygon de OnFinality ofrece endpoints dedicados con límites más altos, pero los números específicos no están documentados públicamente. Siempre consulta la documentación de tu proveedor para obtener los detalles más precisos.

• Límites de solicitudes por segundo (RPS): recuento simple de solicitudes HTTP.
• Límites de unidades de cómputo (CU): costo ponderado según el método y los parámetros.
• Encabezado Retry-After: te indica cuánto tiempo esperar antes de reintentar.
• Error JSON-RPC -32005: a veces se usa en lugar de HTTP 429.

Desencadenantes Comunes de Errores 429 en Polygon

Varios patrones comunes conducen a errores 429 en los endpoints RPC de Polygon. Comprender estos desencadenantes te ayuda a diagnosticarlos y prevenirlos.

Rangos amplios de eth_getLogs: Escanear un rango de bloques grande (por ejemplo, 100,000 bloques) en una sola llamada es extremadamente intensivo en cómputo. Esta es una causa frecuente de errores 429, especialmente al indexar eventos para un token o contrato.

Bucles de sondeo de eth_getBalance: Muchas aplicaciones consultan el saldo de un conjunto de direcciones cada pocos segundos. Si tienes cientos de direcciones, esto puede exceder fácilmente los límites de RPS.

Consultas de getProof y estado de archivo: Métodos como eth_getProof requieren acceso al estado histórico y son costosos. Usarlos en bucles o con parámetros amplios puede activar los límites de tasa.

Indexación ráfaga: Cuando se extrae un nuevo bloque, algunas aplicaciones disparan inmediatamente una ráfaga de solicitudes para obtener todas las transacciones y registros. Esta ráfaga puede exceder el límite por segundo incluso si la tasa promedio es baja.

Diagnóstico de Errores 429: Distinción de Otros Errores de Transporte

Antes de implementar soluciones, debes confirmar que el error es efectivamente un límite de tasa y no un problema de red o un error del servidor. Así es como distinguirlos:

HTTP 429: El código de estado de la respuesta es 429. El cuerpo puede contener un objeto de error JSON-RPC con código -32005 o un mensaje de texto plano. El encabezado Retry-After suele estar presente.

HTTP 5xx: Si ves 500, 502 o 503, el servidor tiene problemas, no tu cliente. Reintentar con retroceso puede ayudar, pero la causa es diferente.

Tiempos de espera de red: Si la solicitud se agota sin respuesta, podría ser un problema de red o el servidor está sobrecargado. Esto no es un 429.

Para ver la respuesta exacta, usa curl con -v para mostrar los encabezados. Por ejemplo, ejecuta el siguiente comando para hacer una llamada simple a eth_blockNumber e inspeccionar los encabezados de la respuesta.

curl -v -X POST https://polygon-rpc.com \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Busca HTTP/1.1 429 en los encabezados de la respuesta.
# Si ves 429, anota el valor del encabezado Retry-After.

Ejemplo Ejecutable: Verificación de Salud y Retroceso en Node.js

A continuación se muestra un script de Node.js autónomo que demuestra dos cosas: una verificación de salud simple (eth_blockNumber) y una función de solicitud robusta con retroceso exponencial que respeta el encabezado Retry-After. Este script utiliza la API fetch integrada (Node.js 18+).

El script define una función rpcRequest que envía una solicitud JSON-RPC a un endpoint dado. Si el estado de la respuesta es 429, lee el encabezado Retry-After (o usa un retraso predeterminado) y espera antes de reintentar, con retroceso exponencial (duplicando el retraso cada vez) hasta un número máximo de reintentos.

// polygon-rpc-backoff.js
// Ejecutar con: node polygon-rpc-backoff.js

const endpoint = 'https://polygon-rpc.com'; // Reemplaza con tu endpoint preferido

async function rpcRequest(method, params, retries = 5) {
  let delay = 1000; // comenzar con 1 segundo
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ jsonrpc: '2.0', method, params, id: 1 })
    });

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const waitMs = retryAfter ? parseInt(retryAfter) * 1000 : delay;
      console.log(`Límite de tasa alcanzado. Esperando ${waitMs}ms antes del reintento ${attempt + 1}`);
      await new Promise(resolve => setTimeout(resolve, waitMs));
      delay *= 2; // retroceso exponencial
    } else {
      const data = await response.json();
      if (data.error) {
        throw new Error(`Error RPC: ${data.error.message}`);
      }
      return data.result;
    }
  }
  throw new Error('Máximo de reintentos excedido');
}

async function main() {
  try {
    const blockNumber = await rpcRequest('eth_blockNumber', []);
    console.log('Número de bloque actual:', parseInt(blockNumber, 16));
  } catch (error) {
    console.error('Falló:', error.message);
  }
}

main();

Resultados Esperados y Cómo Verificarlos

Cuando ejecutes el script, deberías ver el número de bloque actual impreso. Si no estás limitado por tasa, se imprimirá inmediatamente. Si estás limitado, verás mensajes de registro sobre espera y reintentos.

Para verificar que el retroceso funciona, puedes enviar intencionalmente muchas solicitudes en un bucle. Por ejemplo, modifica el script para llamar a rpcRequest('eth_blockNumber', []) 100 veces en un bucle cerrado. Deberías observar que después de algunas solicitudes, comienzas a recibir respuestas 429 y el script espera antes de continuar.

Nota: El endpoint público https://polygon-rpc.com puede tener límites estrictos. Si estás construyendo una aplicación de producción, considera usar un endpoint dedicado de un proveedor como el servicio API de OnFinality para obtener límites más altos y mejor fiabilidad.

Soluciones: Procesamiento por Lotes de Solicitudes JSON-RPC

Una de las formas más efectivas de reducir el número de solicitudes HTTP es usar solicitudes por lotes JSON-RPC. En lugar de enviar múltiples solicitudes individuales, puedes enviar un array de objetos de solicitud en una sola publicación HTTP. Esto reduce la sobrecarga y te ayuda a mantenerte dentro de los límites de RPS.

Por ejemplo, si necesitas obtener saldos de 100 direcciones, puedes agrupar las 100 llamadas eth_getBalance en una sola solicitud. El servidor las procesa y devuelve un array de resultados. Esto es especialmente útil para bucles de sondeo.

Aquí hay un ejemplo de Node.js usando fetch para enviar una solicitud por lotes:

// batch-example.js
const endpoint = 'https://polygon-rpc.com';

const requests = [];
for (let i = 0; i < 100; i++) {
  requests.push({
    jsonrpc: '2.0',
    method: 'eth_getBalance',
    params: [`0x${i.toString(16).padStart(40, '0')}`, 'latest'],
    id: i
  });
}

const response = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requests)
});

const results = await response.json();
console.log(results.length); // debería ser 100

Soluciones: Usa Suscripciones WebSocket en Lugar de Sondeo

Para datos en tiempo real como nuevos bloques o transacciones pendientes, el sondeo es ineficiente y puede activar límites de tasa. En su lugar, usa suscripciones WebSocket. Polygon RPC admite los métodos WebSocket estándar de Ethereum como eth_subscribe y eth_unsubscribe.

Con WebSocket, mantienes una conexión persistente y recibes notificaciones push cuando ocurren eventos. Esto reduce drásticamente el número de solicitudes. Por ejemplo, para escuchar nuevos encabezados de bloque, puedes suscribirte a newHeads.

Aquí hay un ejemplo mínimo usando el paquete ws (instala con npm install ws):

// ws-subscribe.js
const WebSocket = require('ws');

const ws = new WebSocket('wss://polygon-rpc.com'); // o el endpoint WS de tu proveedor

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_subscribe',
    params: ['newHeads'],
    id: 1
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  if (message.method === 'eth_subscription') {
    const block = message.params.result;
    console.log('Nuevo bloque:', parseInt(block.number, 16));
  }
});

ws.on('error', (err) => console.error('Error WS:', err));

Soluciones: Reduce los Rangos de eth_getLogs y Divide por Ventanas de Bloques

Si debes usar eth_getLogs, evita rangos de bloques amplios. En su lugar, divide tu consulta en ventanas de bloques más pequeñas (por ejemplo, 10,000 bloques cada una) y procésalas secuencialmente o en paralelo con una concurrencia controlada. Esto reduce el costo computacional por solicitud y ayuda a evitar alcanzar los límites de CU.

Por ejemplo, si necesitas escanear desde el bloque 10,000,000 hasta el 10,100,000, puedes hacer 10 solicitudes de 10,000 bloques cada una. También puedes usar los parámetros fromBlock y toBlock para especificar el rango.

Además, usa los filtros address y topics para reducir los registros que te interesan. Esto reduce la cantidad de datos devueltos y el costo computacional.

// Ejemplo: dividir eth_getLogs en ventanas
const startBlock = 10000000;
const endBlock = 10100000;
const windowSize = 10000;

for (let from = startBlock; from < endBlock; from += windowSize) {
  const to = Math.min(from + windowSize - 1, endBlock);
  const params = [{
    fromBlock: '0x' + from.toString(16),
    toBlock: '0x' + to.toString(16),
    address: '0x...', // opcional
    topics: [] // opcional
  }];
  // Enviar solicitud con retroceso
  const logs = await rpcRequest('eth_getLogs', params);
  // Procesar registros
}

Soluciones: Almacena en Caché el Estado y Usa Indexadores Locales

Para datos que no cambian con frecuencia, como saldos de tokens o estado de contratos, almacena los resultados en caché localmente y actualízalos solo en intervalos. Esto reduce significativamente el número de llamadas RPC.

Para cargas de trabajo de indexación pesadas, considera ejecutar tu propio indexador o usar un servicio como The Graph. Esto traslada la carga de consultas del endpoint RPC por completo.

Si necesitas datos de archivo, considera usar un proveedor de nodos de archivo dedicado. OnFinality ofrece nodos Polygon dedicados que pueden manejar altas cargas de consultas.

Soluciones: Retroceso Exponencial y Retry-After

Incluso con optimizaciones, aún puedes encontrar errores 429. Implementar retroceso exponencial respetando el encabezado Retry-After es esencial para la resiliencia. El script de ejemplo anterior demuestra esto.

Puntos clave: siempre lee el encabezado Retry-After si está presente; si no, usa un retraso predeterminado (por ejemplo, 1 segundo) y duplícalo en cada reintento. Establece un número máximo de reintentos para evitar bucles infinitos.

También considera agregar jitter (retraso aleatorio) para evitar el efecto de manada atronadora cuando muchos clientes reintentan simultáneamente.

Compensaciones y Limitaciones

Aunque estas soluciones ayudan, tienen compensaciones. El procesamiento por lotes aumenta el tamaño del payload y puede alcanzar los límites de tamaño de solicitud. Las suscripciones WebSocket requieren mantener una conexión persistente y manejar reconexiones. Reducir los rangos de eth_getLogs aumenta el número de solicitudes, lo que podría aún alcanzar los límites de RPS si no se gestiona cuidadosamente.

Los endpoints públicos son gratuitos pero tienen límites estrictos y sin SLA. Para aplicaciones de producción, considera usar un proveedor comercial como OnFinality, que ofrece límites más altos, endpoints dedicados y soporte. Consulta la página de precios para más detalles.

Recuerda que las políticas de límite de tasa varían según el proveedor. Siempre consulta la documentación de tu proveedor para conocer los límites específicos y las mejores prácticas.

Lista de Verificación para Manejar Errores 429

Usa esta lista de verificación para abordar sistemáticamente los errores 429 en Polygon RPC:

1. Confirma que el error es 429 (verifica los encabezados y el cuerpo).
2. Identifica el desencadenante: eth_getLogs amplio, bucles de sondeo, indexación ráfaga, etc.
3. Implementa el procesamiento por lotes para múltiples solicitudes independientes.
4. Usa suscripciones WebSocket para datos en tiempo real.
5. Reduce los rangos de eth_getLogs y divide en ventanas.
6. Almacena en caché el estado y usa indexadores locales cuando sea posible.
7. Implementa retroceso exponencial con manejo de Retry-After.
8. Si la carga sostenida es alta, considera un endpoint dedicado de un proveedor.

• Verifica si el endpoint es público o específico del proveedor.
• Monitorea tu tasa de solicitudes y el uso de unidades de cómputo.
• Usa el encabezado Retry-After para programar reintentos.
• Considera usar un endpoint Polygon dedicado para producción.

Próximos Pasos y Lecturas Adicionales

Ahora que comprendes los límites de tasa de Polygon RPC, puedes aplicar estas técnicas a tu aplicación. Para obtener orientación más detallada, explora la guía de Polygon RPC en el Asistente RPC de OnFinality. También puedes leer nuestro artículo genérico sobre solución de problemas de RPC 429 para obtener información más amplia.

Si necesitas un endpoint confiable para producción, considera el servicio API de OnFinality o los nodos Polygon dedicados. Nuestra página de precios ofrece planes transparentes. Para más recursos de aprendizaje, visita la sección OnFinality Learn.