Error de tiempo de espera de RPC: causas, diagnóstico y soluciones

¿Qué es un error de tiempo de espera de RPC?

Un error de tiempo de espera de RPC es una excepción del lado del cliente que se produce cuando una solicitud JSON-RPC a un nodo de blockchain no se completa dentro de un límite de tiempo especificado. El cliente envía una solicitud (por ejemplo, eth_getBlockByNumber) y espera una respuesta; si el nodo no responde antes de que expire el tiempo de espera, el cliente aborta la solicitud y muestra un error como TimeoutError, ETIMEDOUT o request timed out.

Los tiempos de espera no son un concepto específico de blockchain: son una parte fundamental de cualquier sistema distribuido. En el contexto de RPC de blockchain, los tiempos de espera pueden ocurrir en múltiples capas: la red (tiempo de espera de conexión TCP), la solicitud HTTP (tiempo de espera de lectura) o la lógica de la aplicación (por ejemplo, esperar un recibo de transacción). Comprender qué capa está fallando es el primer paso para solucionar problemas.

Este artículo se centra en JSON-RPC compatible con Ethereum, pero los principios se aplican a otras cadenas como Solana y Polkadot. Para una visión más amplia de los endpoints de RPC, consulte nuestra guía de endpoints de RPC.

• Tiempo de espera del lado del cliente: el cliente abandona la espera de una respuesta.
• Tiempo de espera del lado del servidor: el nodo o proveedor termina una solicitud lenta.
• Tiempo de espera de red: los paquetes se pierden o se retrasan más allá de los umbrales aceptables.

Causas comunes de los tiempos de espera de RPC

Los tiempos de espera de RPC rara vez son causados por un solo factor. Por lo general, se derivan de una combinación de condiciones de red, rendimiento del nodo y configuración del cliente. Las causas más comunes incluyen:

Latencia de red y pérdida de paquetes – Si su cliente está geográficamente distante del endpoint de RPC, o si la ruta de red está congestionada, el tiempo de ida y vuelta (RTT) puede exceder su tiempo de espera. Esto es especialmente común cuando se utilizan endpoints públicos que están lejos.

Nodos sobrecargados o con recursos insuficientes – Un nodo que se está sincronizando, procesando muchas solicitudes o ejecutándose en hardware insuficiente puede responder lentamente. Los endpoints públicos a menudo limitan la velocidad o ponen en cola las solicitudes, lo que causa demoras.

Solicitudes grandes o costosas – Algunos métodos de RPC, como eth_getLogs con un amplio rango de bloques, pueden tardar segundos en ejecutarse. Si su tiempo de espera de cliente está configurado en 2 segundos, dichas solicitudes inevitablemente agotarán el tiempo.

Tiempos de espera de cliente mal configurados – Muchas bibliotecas tienen tiempos de espera cortos por defecto (por ejemplo, 10 segundos en web3.js, 30 segundos en ethers). Si su aplicación no establece explícitamente un tiempo de espera, puede estar utilizando un valor demasiado bajo para su caso de uso.

Problemas del lado del proveedor – Los proveedores de RPC pueden tener sus propias políticas de tiempo de espera. Por ejemplo, un proveedor puede terminar solicitudes que tardan más de 30 segundos. Si su solicitud es lenta, puede ver un tiempo de espera incluso si su cliente está configurado correctamente.

• Verifique el tiempo de espera predeterminado de su cliente y ajústelo según sus patrones de solicitud.
• Use un proveedor con un acuerdo de nivel de servicio (SLA) que garantice tiempos de respuesta.

Diagnóstico de tiempos de espera de RPC con curl

La forma más rápida de diagnosticar un tiempo de espera de RPC es usar curl para enviar una solicitud y medir el tiempo. La opción -w muestra los detalles de tiempo, y --max-time establece un tiempo de espera para toda la solicitud. Aquí hay un comando que envía una solicitud simple eth_blockNumber a un endpoint público de Ethereum:

curl -s -o /dev/null -w "connect: %{time_connect}s\nttfb: %{time_starttransfer}s\ntotal: %{time_total}s\n" --max-time 10 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

La salida muestra el tiempo para establecer una conexión TCP (time_connect), el tiempo para recibir el primer byte (time_starttransfer) y el tiempo total. Si time_connect es alto, tiene un problema de red. Si time_connect es bajo pero time_starttransfer es alto, el nodo es lento para responder.

Si el comando agota el tiempo (código de salida 28), sabe que el endpoint no responde dentro de su límite. Pruebe la misma solicitud contra un endpoint diferente, como un endpoint de RPC dedicado, para ver si el problema es específico del proveedor.

curl -s -o /dev/null -w "connect: %{time_connect}s\nttfb: %{time_starttransfer}s\ntotal: %{time_total}s\n" --max-time 10 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Prueba con una solicitud pesada

Una solicitud simple eth_blockNumber es rápida, pero muchos tiempos de espera ocurren con métodos más pesados. Para reproducir un tiempo de espera, envíe una solicitud que requiera más cómputo, como eth_getLogs en un amplio rango de bloques. Use los mismos indicadores de tiempo de curl para ver cuánto tarda:

curl -s -o /dev/null -w "total: %{time_total}s\n" --max-time 30 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1000000","toBlock":"0x1000100","address":"0x..."}],"id":1}'

Si esto agota el tiempo, tiene una solicitud demasiado pesada para el endpoint. En producción, debe evitar tales solicitudes o usar el procesamiento por lotes y la paginación. Consulte nuestra guía sobre mejores prácticas de procesamiento por lotes JSON-RPC para estrategias que reduzcan el tamaño de la carga útil.

También tenga en cuenta que algunos proveedores imponen sus propios límites en eth_getLogs (por ejemplo, rango máximo de bloques). Si excede esos límites, puede obtener un error o un tiempo de espera.

curl -s -o /dev/null -w "total: %{time_total}s\n" --max-time 30 -X POST https://eth.api.onfinality.io/public -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1000000","toBlock":"0x1000100","address":"0x..."}],"id":1}'

Configuración del tiempo de espera en el cliente

La mayoría de las bibliotecas Web3 le permiten establecer un tiempo de espera. En ethers.js, puede pasar una opción timeout al proveedor o usar request con un tiempo de espera. En web3.js, puede establecer timeout en las opciones del proveedor. Aquí hay un ejemplo con ethers.js:

const { ethers } = require("ethers");
const provider = new ethers.JsonRpcProvider("https://eth.api.onfinality.io/public", undefined, { timeout: 15000 });

Establecer un tiempo de espera demasiado bajo causará tiempos de espera frecuentes en redes lentas. Una práctica común es establecer un tiempo de espera de 15-30 segundos para solicitudes estándar, y hasta 60 segundos para operaciones pesadas como eth_getLogs o eth_call que involucran lógica de contratos compleja.

Si está utilizando una biblioteca que no expone un tiempo de espera, puede envolver su solicitud en un Promise.race con un temporizador. Esto le da un control fino sobre el tiempo de espera para cada llamada.

Recuerde que los tiempos de espera no son un sustituto del manejo adecuado de errores. Siempre capture los errores de tiempo de espera e implemente lógica de reintentos con retroceso exponencial. Para más información, consulte nuestra guía de monitoreo de endpoints de RPC.

const { ethers } = require("ethers");
const provider = new ethers.JsonRpcProvider("https://eth.api.onfinality.io/public", undefined, { timeout: 15000 });

Tiempos de espera y límites del lado del proveedor

Los proveedores de RPC a menudo tienen sus propias políticas de tiempo de espera. Por ejemplo, un proveedor puede terminar cualquier solicitud que tarde más de 30 segundos. Esto es para proteger su infraestructura del agotamiento de recursos. Si su solicitud es lenta, puede ver un tiempo de espera incluso si su cliente está configurado correctamente.

Los proveedores también imponen límites de velocidad y límites de concurrencia. Si excede estos, puede recibir errores HTTP 429 o 503, que pueden confundirse con tiempos de espera. Verifique los encabezados de respuesta para x-ratelimit-* o similares.

Al elegir un proveedor de RPC, considere su SLA y garantías de rendimiento. OnFinality, por ejemplo, ofrece endpoints dedicados sin límites de velocidad y monitoreo 24/7. Puede comparar proveedores en nuestra guía de mejores proveedores de RPC.

Si está ejecutando su propio nodo, asegúrese de que esté bien aprovisionado (CPU, RAM, disco) y no se esté quedando atrás en la red. Un nodo que aún se está sincronizando responderá lentamente o no responderá en absoluto.

• Consulte la documentación del proveedor para conocer las políticas de tiempo de espera y límites de velocidad.
• Use un proveedor que ofrezca endpoints dedicados para cargas de trabajo de producción.

Tiempos de espera a nivel de red y cortafuegos

A veces el problema no es el nodo sino la ruta de red. Los cortafuegos, proxies y balanceadores de carga pueden introducir latencia o perder paquetes. Para diagnosticar, use ping y traceroute para medir la latencia y la pérdida de paquetes hacia el hostname del endpoint de RPC.

ping -c 10 eth.api.onfinality.io
traceroute eth.api.onfinality.io

Si ve alta latencia o pérdida de paquetes, considere usar un endpoint diferente que esté geográficamente más cerca. Muchos proveedores ofrecen endpoints en múltiples regiones. OnFinality, por ejemplo, tiene una red global de nodos; puede seleccionar el más cercano a través de nuestra página de redes.

También verifique su cortafuegos local o la configuración del proxy corporativo. Algunas redes bloquean o limitan el tráfico a puertos o hosts desconocidos. Si está detrás de un proxy, asegúrese de que su cliente de RPC esté configurado para usarlo.

ping -c 10 eth.api.onfinality.io
traceroute eth.api.onfinality.io

Mensajes de error comunes y su significado

Diferentes clientes y proveedores devuelven diferentes mensajes de error para los tiempos de espera. Aquí hay algunos comunes y lo que significan:

| Mensaje de error | Causa probable |

|---------------|--------------|

| ETIMEDOUT | Se agotó el tiempo de espera de la conexión de red (conexión TCP o lectura). |

| TimeoutError | Se excedió el tiempo de espera del lado del cliente. |

| request timed out | Tiempo de espera genérico del cliente HTTP. |

| ECONNRESET | Conexión restablecida por el servidor (a menudo debido a límites de velocidad o sobrecarga del servidor). |

| 429 Too Many Requests | Se excedió el límite de velocidad, no es un tiempo de espera pero a menudo se confunde. |

| 503 Service Unavailable | Servidor sobrecargado o en mantenimiento. |

Si ve ECONNRESET o 429, es probable que esté alcanzando los límites de velocidad. En ese caso, reduzca su tasa de solicitudes o use un proveedor con límites más altos. Para los tiempos de espera, concéntrese en las causas discutidas anteriormente.

• Registre siempre el objeto de error completo, incluido el seguimiento de pila y los encabezados de respuesta.
• Use un ID de correlación para rastrear solicitudes a través de su sistema.

Prevención de tiempos de espera de RPC en producción

Para minimizar los tiempos de espera de RPC en producción, adopte las siguientes prácticas:

Use un proveedor de RPC confiable – Elija un proveedor con un historial comprobado y SLA. Evite los endpoints públicos gratuitos para aplicaciones críticas.

Establezca tiempos de espera apropiados – Configure los tiempos de espera según el tiempo de respuesta esperado de cada método. Use tiempos de espera más largos para operaciones pesadas.

Implemente lógica de reintentos – Reintente las solicitudes fallidas con retroceso exponencial y jitter. Esto maneja problemas transitorios de red.

Procese por lotes las solicitudes – Combine múltiples llamadas RPC en un solo lote JSON-RPC para reducir el número de idas y vueltas. Consulte nuestra guía de procesamiento por lotes.

Almacene en caché las respuestas – Almacene en caché los datos solicitados con frecuencia (por ejemplo, precios de tokens, números de bloque) para reducir la carga en los endpoints de RPC.

Monitoree el rendimiento – Use herramientas para rastrear la latencia de RPC y las tasas de error. Nuestra guía de monitoreo proporciona pasos prácticos.

Use un balanceador de carga – Si tiene múltiples endpoints, distribuya las solicitudes entre ellos para evitar sobrecargar un solo nodo.

• Considere usar un servicio de API dedicado que maneje el escalado y la conmutación por error por usted.

Compensaciones y limitaciones

Aumentar los tiempos de espera puede enmascarar problemas subyacentes. Si sus solicitudes tardan consistentemente más de lo esperado, debe investigar la causa raíz en lugar de simplemente aumentar el tiempo de espera. Los tiempos de espera largos también inmovilizan los recursos del cliente y pueden llevar a una mala experiencia de usuario.

La lógica de reintentos puede causar transacciones duplicadas si reintenta una solicitud que realmente se procesó pero la respuesta se perdió. Use claves de idempotencia o verifique los hashes de transacción antes de reintentar.

El procesamiento por lotes reduce las idas y vueltas pero puede aumentar el tamaño de la carga útil, lo que puede alcanzar los límites del proveedor. Siempre verifique el tamaño máximo de lote admitido por su proveedor.

Finalmente, ninguna solución es perfecta. Incluso con las mejores prácticas, los tiempos de espera ocasionales son inevitables debido a la imprevisibilidad de la red. Diseñe su aplicación para manejarlos con gracia.

Próximos pasos

Ahora que comprende los tiempos de espera de RPC, puede tomar medidas concretas para diagnosticarlos y solucionarlos. Comience ejecutando los comandos curl de este artículo contra sus endpoints para medir la latencia de referencia. Luego, ajuste los tiempos de espera de su cliente e implemente lógica de reintentos.

Para más lectura, explore nuestro Asistente de RPC para más guías de solución de problemas, o aprenda cómo reducir la latencia de RPC para mejorar el rendimiento.

Si está evaluando proveedores de RPC, compare precios y características para encontrar una solución que satisfaga sus necesidades.