Corriger l’erreur Binance API -1021
Erreur d’horodatage Binance API -1021 : corriger la dérive de l’horloge d’un bot de trading auto-hébergé
Un bot de trading auto-hébergé peut signer correctement une requête et malgré tout se la voir refuser par Binance. L’erreur -1021 indique un problème d’horodatage : l’heure de la requête signée est en dehors de la fenêtre acceptée par Binance, ou elle est en avance sur l’heure du serveur. Pour savoir comment corriger l’erreur Binance API -1021, commencez par vérifier l’horloge de l’environnement d’exécution plutôt que de modifier votre logique de trading. La solution consiste généralement à intervenir sur la machine qui exécute le bot, et non sur le code de la stratégie.
Ne faites qu’une seule modification à la fois. Commencez par relever l’erreur, vérifiez ensuite l’horloge de l’environnement d’exécution et rétablissez la synchronisation de l’heure. Ce n’est qu’après cela que vous pourrez ajuster la gestion des horodatages ou recvWindow. En procédant dans cet ordre, vous éviterez de masquer un problème d’horloge de l’hôte en élargissant la fenêtre de requête.
1. Vérifiez qu’il s’agit bien d’une erreur de décalage d’horloge -1021
Lisez le corps complet de la réponse, pas seulement le statut HTTP ou une ligne de journal tronquée. Le code d’erreur et le message de l’API Binance doivent indiquer que l’horodatage est en dehors de la fenêtre autorisée ou qu’il est en avance sur l’heure du serveur.
Cette réponse est différente de celles provoquées par une signature mal formée, une clé API manquante ou un problème d’autorisations. Ces problèmes renvoient généralement d’autres codes ou messages d’erreur. Si le code est -1021, concentrez-vous d’abord sur l’horodatage signé, l’horloge du serveur et la valeur configurée pour recvWindow ; ne commencez pas par renouveler les clés ou modifier les autorisations de trading.
Vérifiez également que l’appel en échec est bien signé. Les requêtes publiques de données de marché n’empruntent pas forcément le même chemin d’authentification, tandis que les points de terminaison liés aux comptes et aux ordres nécessitent généralement des requêtes signées. Si le bot échoue uniquement lors des appels signés, c’est un indice utile.
2. Reproduisez l’erreur avec une seule requête signée
Mettez en pause le placement d’ordres avant de commencer l’investigation. Utilisez un point de terminaison signé minimal, en lecture seule, auquel votre clé API est autorisée à accéder. Vous éviterez ainsi de créer ou d’annuler des ordres pendant la collecte des éléments nécessaires. Si la clé n’a pas accès à ce point de terminaison, utilisez un autre point de terminaison en lecture seule compatible avec la version de l’API Binance utilisée par le bot.
Notez l’horodatage exact de la requête, le point de terminaison, le statut de la réponse, le code et le message d’erreur Binance, ainsi que l’heure à laquelle la requête a quitté votre processus. Masquez la clé API, la signature, les données du compte et tout autre secret dans les journaux. Ne publiez jamais une URL signée ou des en-têtes d’authentification complets dans un ticket public ou une conversation.
Limitez-vous à une reproduction simple.
Exécutez-la depuis le même environnement de processus que celui où l’erreur s’est produite. L’horloge de l’hôte peut être correcte dans un terminal alors qu’un conteneur, une machine virtuelle ou un processus en arrière-plan utilise une configuration d’exécution différente. Si une requête en lecture seule réussit après la correction de l’horloge, comparez son horodatage et sa réponse avec ceux de l’échec enregistré avant de redémarrer toute la boucle de trading.
3. Comparez l’horloge de l’hôte à une source horaire fiable
Pour vérifier le décalage horaire d’un serveur Linux, examinez l’heure UTC et l’état de synchronisation sur la machine ou l’hôte du conteneur qui exécute réellement le bot. Des commandes comme date -u et timedatectl status peuvent afficher l’heure UTC et indiquer si la synchronisation de l’heure système est active. Les commandes disponibles dépendent de la distribution et du service horaire installé.
Ne confondez pas l’affichage du fuseau horaire avec une dérive de l’horloge. Un hôte configuré sur un fuseau horaire local peut afficher une heure différente de l’heure UTC tout en indiquant le bon instant. Comparez des valeurs UTC ou des horodatages Unix, pas seulement l’heure affichée par une horloge de bureau.
Les conteneurs partagent généralement l’horloge système de l’hôte au lieu de disposer d’une horloge indépendante, mais leur comportement dépend de la plateforme et de l’environnement d’exécution. Vérifiez également le nœud ou la machine virtuelle qui exécute le conteneur. Dans un environnement orchestré, identifiez le nœud de travail précis qui a traité la requête en échec ; en vérifier un autre pourrait donner un résultat normal sans expliquer l’incident.
Recherchez un décalage mesurable et vérifiez l’état de synchronisation, au lieu de vous fier à une date qui semble plausible. Une horloge décalée de plusieurs secondes peut suffire à provoquer un rejet d’horodatage, selon la fenêtre de requête et les conditions réseau.
4. Rétablissez la synchronisation de l’heure sur l’hôte d’exécution réel
Utilisez le service de synchronisation horaire pris en charge par l’hôte. Sur un système géré avec systemd, vérifiez systemd-timesyncd ou l’alternative configurée, comme Chrony ; ne partez pas du principe que l’activation d’un service signifie qu’il est la source horaire utilisée. Après avoir appliqué la configuration habituelle de l’hôte, vérifiez l’état du service et l’état de synchronisation qu’il indique.
Sur une machine virtuelle dans le cloud, assurez-vous que le service horaire de l’invité fonctionne avec la source recommandée par le fournisseur. Si la machine virtuelle a été mise en pause, reprise, migrée ou restaurée depuis un instantané, vérifiez à nouveau son horloge avant de remettre le bot en ligne. Certains environnements corrigent l’heure progressivement : un processus lancé juste après un important saut d’horloge peut donc continuer à signer incorrectement les requêtes pendant un court moment.
Pour un conteneur, rétablissez la synchronisation sur son hôte ou son nœud d’orchestration, plutôt que d’essayer de régler l’horloge du conteneur. Les conteneurs n’ont généralement pas l’autorisation de modifier l’heure système, et accorder cette autorisation à un bot de trading n’est pas une solution de contournement raisonnable. Une fois la synchronisation rétablie, vérifiez que l’hôte d’exécution réel indique un état de synchronisation actif ; le simple fait que le service soit « activé » ne prouve pas qu’il a contacté une source horaire.
Ne redémarrez le bot qu’après avoir vérifié l’horloge de l’hôte. Envoyez ensuite à nouveau la même requête en lecture seule et enregistrez sa réponse. Si l’erreur persiste, comparez l’horodatage de la requête à l’heure du serveur Binance avant de modifier le code de signature du bot.
5. Mesurez le décalage avec l’heure du serveur Binance avant de signer les requêtes
Binance met à disposition un point de terminaison public qui renvoie l’heure du serveur. Interrogez-le juste avant ou pendant un test contrôlé, et notez l’horodatage du serveur ainsi que l’heure locale autour de la requête. Vous pourrez ainsi comparer directement l’heure utilisée par le bot à celle du serveur.
La latence réseau influe sur cette comparaison. Pour obtenir une estimation simple au point médian, notez l’heure locale d’envoi et de réception, puis comparez l’heure renvoyée par Binance au milieu de l’intervalle. Par exemple, si une requête part à l’heure locale t1 et revient à t2, utilisez le milieu entre t1 et t2 comme estimation approximative de l’heure locale au moment où le serveur a généré sa réponse. Le décalage obtenu reste approximatif, car le trajet réseau peut être asymétrique et le temps de traitement du point de terminaison n’est pas nécessairement nul.
Répétez la mesure plusieurs fois et privilégiez une estimation stable obtenue à partir de réponses ayant un faible temps aller-retour. Ne considérez pas une seule réponse retardée comme une mesure fiable de l’heure.
Si l’horloge de l’hôte diffère sensiblement de l’estimation fondée sur l’heure du serveur, rétablissez d’abord la synchronisation. Un décalage géré au niveau de l’application peut aider à compenser de faibles différences mesurées, mais ne doit pas remplacer durablement un service horaire fonctionnel sur l’hôte.
6. Mettez en place une stratégie sûre de décalage et de recvWindow
Si le bot doit appliquer une correction de décalage, calculez-la à partir de plusieurs mesures de l’heure du serveur et appliquez-la lors de la génération de l’horodatage signé. Cette méthode peut aider à synchroniser l’horloge d’un bot Binance lorsque de faibles différences sont mesurées. Conservez la correction en mémoire ou dans une valeur de configuration contrôlée, actualisez-la selon un calendrier défini et consignez le décalage mesuré ainsi que l’horodatage utilisé pour chaque requête en échec. Évitez de coder en dur une valeur copiée d’un seul test : la latence réseau et les conditions de l’hôte peuvent évoluer.
Appliquez le décalage avant de signer. L’horodatage inclus dans les paramètres signés doit être celui couvert par la signature ; le modifier après la génération de celle-ci l’invalide. Testez cet enchaînement avec un point de terminaison en lecture seule avant d’autoriser le bot à passer des ordres.
Une légère augmentation de recvWindow peut absorber la latence réseau habituelle ou de petites variations temporelles. Elle ne corrigera pas une horloge d’hôte constamment déréglée. Une fenêtre trop large peut aussi rendre acceptables des requêtes retardées plus longtemps que prévu ; choisissez donc la valeur la plus faible compatible avec la latence mesurée du bot et les règles de l’API.
N’utilisez qu’un seul mécanisme de correction à la fois. Si l’horloge de l’hôte est synchronisée et que le décalage mesuré est proche de zéro, supprimez les ajustements superflus au niveau de l’application plutôt que de cumuler un décalage calculé à partir de l’heure du serveur et la correction d’une autre bibliothèque. Vérifiez le comportement de la bibliothèque cliente concernant les horodatages avant d’ajouter du code personnalisé.
7. Testez le rétablissement et prévenez les dérives de l’horloge
Renvoyez la même requête signée en lecture seule et vérifiez que la réponse ne contient plus -1021. Comparez son horodatage, le décalage mesuré par rapport à l’heure du serveur et le temps aller-retour avec ceux de l’échec précédent. Ne reprenez le traitement des ordres qu’ensuite, de préférence dans un mode de test ou à faible risque, si votre configuration le permet.
Consignez le nom de l’hôte ou du nœud, l’horodatage local, le décalage mesuré et le code d’erreur de l’API. Déclenchez une alerte en cas d’erreurs d’horodatage répétées plutôt qu’à la moindre erreur isolée : une série d’erreurs après un redémarrage peut indiquer que la synchronisation n’est pas encore terminée, tandis que des échecs récurrents sur un seul nœud suggèrent un problème propre à cet hôte.
Revérifiez l’horloge après la mise en pause d’une machine virtuelle, les redémarrages, les migrations de conteneurs et les redémarrages du service horaire. Si les erreurs réapparaissent après une modification de l’hôte, suspendez le placement d’ordres et vérifiez le nœud qui a traité la requête avant d’augmenter recvWindow. Cela peut éviter qu’une horloge désynchronisée transforme un incident temporaire d’infrastructure en une série d’ordres rejetés.