Error de timestamp -1021 de la API de Binance: cómo corregir el desfase del reloj en un bot de trading autohospedado
Un bot de trading autohospedado puede firmar una solicitud correctamente y, aun así, Binance puede rechazarla. El error -1021 indica un problema con el timestamp: la hora de la solicitud firmada está fuera del intervalo que Binance acepta o es posterior a la hora del servidor. Normalmente, la solución empieza en la máquina donde se ejecuta el bot, no en el código de la estrategia. Si buscas «cómo solucionar el error -1021 de Binance», empieza por comprobar el reloj del entorno de ejecución en lugar de cambiar la lógica de trading.
Haz un cambio a la vez. Primero registra el fallo; después, comprueba el reloj del entorno de ejecución y restablece la sincronización horaria. Solo entonces ajusta la gestión del timestamp o recvWindow. Seguir este orden ayuda a evitar que un valor mayor para la ventana de solicitud oculte un problema con el reloj del host.
1. Confirma que -1021 se debe a un desfase del reloj
Lee el cuerpo completo de la respuesta, no solo el estado HTTP o una línea abreviada del registro. El código y el mensaje de error de la API de Binance deberían indicar que el timestamp está fuera del intervalo permitido o que es posterior a la hora del servidor.
Esta respuesta es distinta de la que se produce por una firma mal formada, una clave de API ausente o un problema de permisos. Por lo general, esos problemas generan otros códigos o mensajes de error de la API. Si el código es -1021, céntrate primero en el timestamp firmado, el reloj del servidor y el valor configurado de recvWindow; no cambies las claves ni los permisos de trading como primera medida.
Comprueba también que la llamada que falla esté firmada. Es posible que las solicitudes públicas de datos de mercado no utilicen el mismo método de autenticación, mientras que los endpoints de cuenta y órdenes suelen requerir solicitudes firmadas. Si el bot falla solo en las llamadas firmadas, tienes una pista útil.
2. Reproduce el fallo con una sola solicitud firmada
Pon en pausa la creación de órdenes antes de investigar. Usa un endpoint firmado, de solo lectura y sencillo, al que tu clave de API tenga permiso para acceder. Así evitarás crear o cancelar órdenes mientras recopilas información. Si la clave no tiene acceso a ese endpoint, usa otro endpoint de solo lectura compatible con la versión de la API de Binance que utiliza el bot.
Registra el timestamp exacto de la solicitud, el endpoint, el estado de la respuesta, el código y el mensaje de error de Binance, y la hora a la que la solicitud salió del proceso. Oculta la clave de API, la firma, los datos de la cuenta y cualquier otro secreto en los registros. Nunca pegues una URL firmada ni un encabezado de autenticación completo en un chat o incidencia públicos.
Procura que la reproducción sea sencilla.
Ejecútala desde el mismo entorno de proceso en el que se produjo el error. Puede que el reloj del host sea correcto, pero que el contenedor, la máquina virtual o el worker utilice una configuración de ejecución distinta. Si una solicitud de solo lectura funciona después de corregir el reloj, compara su timestamp y respuesta con el fallo registrado antes de reiniciar el ciclo completo de trading.
3. Compara el reloj del host con una fuente horaria fiable
Comprueba la hora UTC y el estado de sincronización en la máquina real o en el host del contenedor donde se ejecuta el bot. En Linux, comandos como date -u y timedatectl status pueden mostrar la hora UTC y si la sincronización del reloj del sistema está activa. Los comandos disponibles dependen de la distribución y del servicio horario instalado.
No confundas la zona horaria mostrada con un desfase del reloj. Un host configurado con una zona horaria local puede mostrar una hora distinta de la UTC y, aun así, representar el mismo instante. Compara valores UTC o timestamps Unix, no solo la hora que muestra el reloj del escritorio.
Normalmente, los contenedores comparten el reloj del sistema del host en lugar de tener uno propio, aunque el comportamiento depende de la plataforma y del entorno de ejecución. Comprueba también el nodo o la máquina virtual donde se ejecuta el contenedor. En entornos de orquestación, identifica el worker concreto que procesó la solicitud fallida; comprobar otro nodo podría arrojar un resultado correcto que no explique el incidente.
Busca un desfase medible y comprueba el estado de sincronización; no te conformes con que la fecha parezca razonable. Un reloj que se atrase o adelante varios segundos puede bastar para que se rechace el timestamp, según la ventana de la solicitud y las condiciones de la red.
4. Restablece la sincronización horaria en el host real del entorno de ejecución
Usa el servicio de sincronización horaria compatible con el host. En un sistema gestionado con systemd, comprueba systemd-timesyncd o la alternativa configurada, como Chrony; no des por hecho que, por habilitar un servicio, este sea la fuente horaria activa. Después de aplicar la configuración habitual del host, comprueba el estado del servicio y el estado de sincronización que informa. Si quieres saber cómo sincronizar el reloj para la API de Binance, asegúrate de verificar que el host real esté sincronizado activamente.
En una máquina virtual en la nube, confirma que el servicio horario del sistema invitado funciona con la fuente recomendada por el proveedor. Si la máquina virtual se pausó, reanudó, migró o restauró desde una instantánea, vuelve a revisar el reloj antes de poner el bot en línea. Algunos entornos ajustan la hora gradualmente, así que un proceso que se inicia justo después de un salto horario grande podría seguir firmando solicitudes de forma incorrecta durante un breve periodo.
Si usas un contenedor, restablece la sincronización en el host o en el nodo de orquestación, en lugar de intentar cambiar el reloj del contenedor. Por lo general, los contenedores no tienen permiso para modificar la hora del sistema, y conceder ese permiso a un bot de trading no es una solución adecuada. Una vez restablecida la sincronización, verifica que el host real del entorno de ejecución indique que está sincronizado activamente; que el servicio esté «habilitado» no demuestra que se haya conectado a una fuente horaria.
Reinicia el bot solo después de comprobar el reloj del host. Luego, vuelve a realizar la misma solicitud de solo lectura y guarda la respuesta. Si el error persiste, compara el timestamp de la solicitud con la hora del servidor de Binance antes de modificar el código de firma del bot.
5. Mide el desfase con la hora del servidor de Binance antes de firmar las solicitudes
Binance ofrece un endpoint público para consultar la hora que informa su servidor. Consúltalo justo antes o durante una prueba controlada y registra tanto el timestamp del servidor como la hora local en torno a la solicitud. Así podrás comparar directamente la hora del servidor con la que utiliza el bot.
La latencia de red afecta a la comparación. Una estimación sencilla del punto medio consiste en registrar la hora local de envío y la de recepción, y luego comparar la hora devuelta por Binance con el punto medio entre ambas. Por ejemplo, si una solicitud sale a la hora local t1 y vuelve a la hora t2, usa el punto medio entre t1 y t2 como estimación aproximada de la hora local en la que el servidor generó la respuesta. El desfase resultante es aproximado, ya que la latencia puede ser distinta en cada sentido y el tiempo de procesamiento del endpoint no es necesariamente cero.
Repite la medición varias veces y prioriza las estimaciones estables obtenidas de respuestas con un tiempo de ida y vuelta bajo. No consideres que una respuesta que tardó mucho sea una medición fiable del reloj.
Si el reloj del host difiere de forma considerable de la estimación basada en la hora del servidor, restablece primero la sincronización. Un ajuste en la aplicación puede ayudar a compensar pequeñas diferencias medidas, pero no debe convertirse en un sustituto permanente de un servicio horario funcional en el host.
6. Aplica una estrategia segura para el desfase y recvWindow
Si te preguntas qué significa recvWindow en Binance, se refiere al intervalo de tiempo durante el cual Binance acepta una solicitud firmada. Si el bot necesita corregir el desfase, calcúlalo a partir de varias mediciones de la hora del servidor y aplícalo al generar el timestamp firmado. Guarda la corrección en memoria o en un valor de configuración controlado, actualízala periódicamente y registra el desfase medido y el timestamp usado en cada solicitud fallida. Evita fijar un valor copiado de una sola prueba: la latencia y las condiciones del host pueden cambiar.
Aplica la corrección antes de firmar. El timestamp incluido en los parámetros firmados debe ser el mismo que queda cubierto por la firma; cambiarlo después de generar la firma la invalida. Prueba esta secuencia con un endpoint de solo lectura antes de permitir que el bot cree órdenes.
Aumentar moderadamente recvWindow puede ayudar a admitir la latencia de red habitual o pequeñas variaciones horarias. No corrige un reloj del host que está constantemente desajustado. Además, una ventana demasiado amplia puede hacer que se acepten solicitudes retrasadas durante más tiempo del previsto, así que mantén el valor tan bajo como permitan la latencia medida del bot y las reglas de la API.
Usa un solo mecanismo de corrección a la vez. Si el reloj del host está sincronizado y el desfase medido es casi cero, elimina los ajustes innecesarios en la aplicación en vez de añadir una corrección basada en la hora del servidor sobre la que ya aplica otra biblioteca. Comprueba cómo gestiona los timestamps la biblioteca cliente antes de añadir código personalizado.
7. Comprueba que el problema se haya resuelto y evita que vuelva a ocurrir
Repite la misma solicitud firmada de solo lectura y confirma que la respuesta ya no contiene -1021. Compara su timestamp, el desfase medido con la hora del servidor y el tiempo de ida y vuelta con los valores del fallo anterior. Solo entonces reanuda la gestión de órdenes, preferiblemente en un modo de prueba o de bajo riesgo que admita tu configuración.
Registra el nombre del host o nodo, el timestamp local, el desfase medido y el código de error de la API. Configura alertas para los errores de timestamp recurrentes en lugar de para un único caso aislado: una serie de errores tras un reinicio podría indicar que la sincronización aún no ha terminado, mientras que los fallos repetidos en un solo nodo apuntan a un problema específico del host.
Vuelve a comprobar el reloj después de pausas de máquinas virtuales, reinicios, migraciones de contenedores y reinicios del servicio horario. Si los errores vuelven a aparecer después de un cambio de host, detén la creación de órdenes e inspecciona el nodo que procesó la solicitud antes de aumentar recvWindow. Así puedes evitar que un reloj desajustado convierta un problema temporal de infraestructura en una serie de órdenes rechazadas.
