Límites de velocidad de Polygon: qué son y cómo evitar errores 429

Qué controla realmente un límite de velocidad de Polygon

Un límite de velocidad de Polygon es un techo sobre cuántas solicitudes JSON-RPC te servirá un endpoint dentro de una ventana de tiempo fija. No es un solo número. Los proveedores suelen aplicar varios límites a la vez: solicitudes por segundo, solicitudes por minuto, conexiones concurrentes y, a veces, un límite separado para métodos costosos como eth_getLogs, debug_traceTransaction o eth_call contra estado de archivo.

Cuando cruzas un límite, el endpoint no te pone en cola cortésmente. Devuelve un HTTP 429 Too Many Requests, cierra un WebSocket o deja que la solicitud expire. Tu cliente ve una llamada fallida, y si reintentas inmediatamente empeoras el problema.

Polygon mainnet (chain ID 137) se ejecuta en Bor para la producción de bloques y Heimdall para los checkpoints, y tanto los endpoints públicos como los gestionados se sitúan delante de esa pila. El límite de velocidad es una propiedad del endpoint que llamas, no de la red Polygon en sí. Esa distinción importa: dos endpoints pueden servir la misma cadena y comportarse de manera completamente diferente bajo carga.

Recomendación rápida: qué endpoint se ajusta a tu tráfico

Antes de ajustar los reintentos, decide si el endpoint que tienes puede soportar la carga que estás enviando. Usa esto como primera aproximación.

Si no estás seguro de en cuál de estos te encuentras, la respuesta honesta suele ser la segunda fila. La mayoría de los equipos superan un endpoint público compartido antes de superar la cadena.

Leer las señales: 429, tiempos de espera y caídas silenciosas

La limitación de velocidad rara vez se anuncia claramente. Estos son los patrones que vale la pena reconocer.

• HTTP 429 con un encabezado Retry-After. La señal más clara. Respeta el encabezado en lugar de reintentar a un intervalo fijo.
• HTTP 429 sin encabezados. Común en endpoints públicos compartidos. Retrocede exponencialmente y añade jitter.
• Tiempos de espera en eth_getLogs. A menudo es un límite de rango o tamaño de resultado en lugar de un límite por segundo.
• Desconexiones de WebSocket. Las suscripciones pueden caerse cuando se alcanzan los límites de conexión; necesitas lógica de reconexión independientemente del proveedor.
• Fallos intermitentes solo bajo carga. Síntoma clásico de límite compartido: bien a 10 solicitudes por segundo, inestable a 50.

Una forma rápida de confirmar la causa es registrar el código de estado y el cuerpo de la respuesta para cada llamada fallida. Muchos proveedores devuelven un objeto de error JSON-RPC con un mensaje que distingue la limitación de una solicitud incorrecta.

# Sondear un endpoint de Polygon e inspeccionar el código de estado y el cuerpo
curl -s -o /tmp/resp.json -w "%{http_code}\n" \
  -X POST https://polygon.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

cat /tmp/resp.json

Ejecuta eso en un bucle corto y observa los códigos de estado. Un flujo constante de 200 significa que estás dentro del límite; un 429 te dice dónde está el techo.

Por qué los endpoints públicos de Polygon limitan tan agresivamente

Los endpoints RPC públicos existen para que cualquiera pueda leer la cadena sin registrarse. Esa apertura es exactamente por lo que sus límites son estrictos. Cada llamador comparte el mismo grupo, por lo que el proveedor tiene que proteger el nodo de que un cliente ruidoso deje sin recursos a todos los demás.

En la práctica, esto significa que los endpoints públicos son buenos para:

• Leer un número de bloque o precio de gas ocasionalmente
• Pruebas manuales en una cartera o un explorador de bloques
• Una ruta de respaldo cuando tu endpoint principal está caído

Son una mala opción para:

• Bucles que sondean cada bloque
• Solicitudes por lotes con cientos de llamadas
• Consultas de registros en rangos amplios de bloques
• Cualquier cosa con un presupuesto de latencia orientado al usuario

En el momento en que tu aplicación tiene usuarios reales, el límite compartido se convierte en un riesgo de producto, no solo en un detalle de ingeniería. Ese es el punto en el que los equipos pasan a un endpoint gestionado con una clave dedicada y, más tarde, a un nodo dedicado cuando necesitan rendimiento predecible o acceso a archivo. Puedes comparar esas opciones en la página de precios de RPC y ver qué cadenas están disponibles en redes RPC compatibles.

Métodos que alcanzan los límites primero

No todos los métodos JSON-RPC cuestan lo mismo. Si estás depurando un límite de velocidad, comprueba si los fallos se agrupan en unas pocas llamadas pesadas.

Los endpoints de Polygon de OnFinality soportan transportes HTTP y WebSocket, por lo que los patrones basados en suscripción están disponibles cuando quieres reemplazar el sondeo por push. Consulta la página de la red Polygon para los detalles actuales de endpoint y transporte.

Patrones del lado del cliente que sobreviven a la limitación

No siempre puedes evitar un límite de velocidad, pero puedes hacer que tu cliente se comporte bien cuando lo alcanza.

Retrocede con jitter. Reintentar inmediatamente convierte una limitación breve en una sostenida. El retroceso exponencial con jitter aleatorio distribuye los reintentos.

async function rpcWithRetry(url, body, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });

    if (res.status !== 429) return res.json();

    const retryAfter = Number(res.headers.get("retry-after")) || 0;
    const base = retryAfter * 1000 || 2 ** attempt * 250;
    const wait = base + Math.random() * 250;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error("RPC rate limit: retries exhausted");
}

Agrupa con cuidado. Las solicitudes por lotes JSON-RPC reducen los viajes de ida y vuelta, pero un lote de 200 llamadas sigue contando como 200 llamadas contra la mayoría de los límites. El agrupamiento ayuda a la latencia, no a la cuota.

Cachea lo que no cambia. Los números de bloque, los IDs de cadena y los datos finalizados se pueden cachear. No vuelvas a obtener un bloque que ya tienes.

Separa las rutas de lectura de las de escritura. Una lectura orientada al usuario no debería competir con un indexador en segundo plano por la misma cuota. Dales claves diferentes o endpoints diferentes.

Añade un endpoint de respaldo. Si tu primario devuelve 429, pasa a uno secundario. Mantén la lógica de conmutación por error simple y registra cuándo se activa, para que sepas con qué frecuencia estás realmente limitado.

Cuándo pasar de un endpoint compartido a un nodo dedicado

Una API RPC gestionada con tu propia clave eleva tu techo y te da visibilidad sobre tu uso. Un nodo dedicado cambia la ecuación de nuevo: obtienes infraestructura reservada para tu carga de trabajo en lugar de un grupo compartido.

Considera un nodo Polygon dedicado cuando:

• Tu tasa de solicitudes es predecible y lo suficientemente alta como para que los límites compartidos sean el factor limitante
• Necesitas datos de archivo o métodos de traza que los endpoints compartidos restringen
• Quieres latencia consistente para una carga de trabajo sensible a la latencia
• Necesitas aislar el tráfico de una aplicación del de otra

Quédate en un endpoint compartido gestionado cuando tu tráfico es a ráfagas, tu combinación de métodos es ligera y prefieres no operar infraestructura. La mayoría de los equipos aterrizan aquí primero y solo pasan a dedicado cuando un método o volumen específico lo fuerza. OnFinality ofrece ambas rutas, y la página de nodo dedicado cubre qué implica la infraestructura reservada.

Una breve lista de verificación de depuración para 429

Cuando aparece un error de límite de velocidad de Polygon en producción, trabaja en esto en orden:

1. Confirma el código de estado y el cuerpo de la respuesta, no solo el error del lado del cliente.
2. Identifica qué método está fallando y si es una de las llamadas pesadas anteriores.
3. Comprueba si los fallos se correlacionan con un despliegue, un trabajo cron o un pico de tráfico.
4. Cuenta tus solicitudes reales por segundo durante la ventana de fallo.
5. Verifica que no estás reintentando sin retroceso, lo que multiplica la carga.
6. Comprueba si un trabajo por lotes y el tráfico de usuarios comparten la misma clave.
7. Si el techo es genuinamente demasiado bajo para tu carga de trabajo, evalúa una clave gestionada o un nodo dedicado.

Los pasos 1 a 4 suelen revelar la causa. Los pasos 5 y 6 son los problemas autoinfligidos más comunes.

Puntos clave

• Un límite de velocidad de Polygon lo aplica el endpoint, no la cadena, y normalmente combina límites por segundo, por minuto y de concurrencia.
• HTTP 429 es la señal más clara, pero los tiempos de espera en eth_getLogs y las caídas de WebSocket también son síntomas de limitación.
• Los endpoints públicos comparten sus límites entre todos los llamadores, lo que los hace inadecuados para tráfico orientado al usuario.
• El retroceso con jitter, el almacenamiento en caché y la separación de rutas de lectura de trabajos por lotes reducen la frecuencia con la que alcanzas los límites.
• Los métodos pesados como eth_getLogs y debug_traceTransaction alcanzan los límites antes que las llamadas simples.
• Pasa a una clave gestionada cuando los límites compartidos se conviertan en un riesgo de producto, y a un nodo dedicado cuando necesites rendimiento reservado o acceso a archivo.

Preguntas frecuentes

¿Cuál es el límite de velocidad de Polygon en endpoints públicos? Varía según el proveedor y normalmente no se publica como un solo número. Los endpoints públicos suelen aplicar límites bajos por segundo y por IP porque la capacidad se comparte entre todos los llamadores. Prueba tu endpoint real en lugar de asumir una cifra.

¿Por qué recibo errores 429 solo a veces? Los 429 intermitentes suelen significar que estás cerca de un límite compartido que otros llamadores también consumen. Tu tráfico está bien la mayor parte del tiempo y por encima del límite durante picos o cuando un trabajo por lotes se ejecuta junto con el tráfico de usuarios.

¿El agrupamiento de solicitudes JSON-RPC evita los límites de velocidad? No. La mayoría de los proveedores cuentan cada llamada dentro de un lote contra tu cuota. El agrupamiento reduce los viajes de red y la latencia, no el número de solicitudes.

¿Cómo manejo los 429 en una conexión WebSocket? Reconéctate con retroceso y vuelve a suscribirte a tus temas. Registra las desconexiones para poder distinguir la limitación de los problemas de red. Los límites de suscripción son independientes de los límites de solicitudes HTTP.

¿Cuándo debería usar un nodo Polygon dedicado en lugar de un endpoint compartido? Cuando los límites compartidos son el factor limitante para tu carga de trabajo, cuando necesitas métodos de archivo o traza, o cuando necesitas latencia consistente. Si tu tráfico es ligero y a ráfagas, un endpoint compartido gestionado suele ser la mejor opción.

¿Puedo aumentar mis límites sin ejecutar un nodo? Sí. Una API RPC gestionada con tu propia clave te da un techo más alto y aislado sin operar infraestructura. Revisa los precios de RPC para comparar opciones y consulta las redes RPC compatibles para disponibilidad.