Errore timestamp API Binance -1021: correggere lo sfasamento dell’orologio in un bot di trading self-hosted
Un bot di trading self-hosted può firmare correttamente una richiesta e vedersela comunque rifiutare da Binance. L’errore -1021 indica un problema con il timestamp: l’ora della richiesta firmata non rientra nell’intervallo accettato da Binance oppure è in anticipo rispetto all’ora del server. Di solito, la soluzione va cercata prima di tutto sulla macchina che esegue il bot, non nel codice della strategia. Se stai cercando «come risolvere errore Binance -1021», inizia controllando l’orologio dell’ambiente di esecuzione, invece di modificare la logica di trading.
Apporta una modifica alla volta. Per prima cosa registra l’errore, poi controlla l’orologio dell’ambiente di esecuzione, ripristina la sincronizzazione dell’ora e solo dopo intervieni sulla gestione dei timestamp o su recvWindow. Seguendo quest’ordine eviterai di mascherare un problema con l’orologio dell’host aumentando l’intervallo consentito per le richieste.
1. Verifica che -1021 indichi uno sfasamento dell’orologio
Leggi l’intero corpo della risposta, non solo lo stato HTTP o una riga di log abbreviata. Il codice e il messaggio di errore dell’API Binance dovrebbero indicare che il timestamp non rientra nell’intervallo consentito oppure è in anticipo rispetto all’ora del server.
Questa risposta è diversa da un errore di firma non valida, una chiave API mancante o un problema di autorizzazioni. Questi casi, in genere, producono codici o messaggi di errore diversi. Se il codice è -1021, concentrati innanzitutto sul timestamp firmato, sull’orologio del server e sul valore configurato di recvWindow; non ruotare le chiavi né modificare le autorizzazioni di trading come prima reazione.
Verifica anche che la chiamata che fallisce sia firmata. Le richieste di dati di mercato pubblici potrebbero non usare lo stesso flusso di autenticazione, mentre gli endpoint per account e ordini richiedono spesso richieste firmate. Se il bot fallisce solo nelle chiamate firmate, hai già un indizio utile: potrebbe trattarsi di un errore timestamp richiesta firmata Binance.
2. Riproduci l’errore con una sola richiesta firmata
Sospendi l’invio degli ordini prima di avviare l’indagine. Usa un endpoint firmato minimo e di sola lettura a cui la tua chiave API possa accedere. In questo modo eviti di creare o annullare ordini mentre raccogli informazioni. Se la chiave non è autorizzata per quell’endpoint, usane un altro di sola lettura supportato dalla versione dell’API Binance utilizzata dal bot.
Registra il timestamp esatto della richiesta, l’endpoint, lo stato della risposta, il codice e il messaggio di errore Binance e l’ora in cui la richiesta è uscita dal processo. Oscura nei log la chiave API, la firma, i dati dell’account e ogni altra informazione riservata. Non condividere mai un URL firmato o un’intestazione di autenticazione completa in una segnalazione pubblica o in una chat.
Mantieni la riproduzione semplice.
Eseguila nello stesso ambiente di processo in cui si è verificato l’errore. La shell sull’host potrebbe avere l’orologio corretto, mentre un container, una macchina virtuale o un worker potrebbero usare una configurazione diversa. Se, dopo aver corretto l’orologio, una richiesta di sola lettura va a buon fine, confrontane il timestamp e la risposta con quelli dell’errore registrato prima di riavviare l’intero ciclo di trading.
3. Confronta l’orologio dell’host con una fonte oraria attendibile
Controlla l’ora UTC e lo stato della sincronizzazione sulla macchina effettiva o sull’host del container che esegue il bot. Su Linux, comandi come date -u e timedatectl status possono mostrare l’ora UTC visualizzata e indicare se la sincronizzazione dell’ora di sistema è attiva; i comandi disponibili dipendono dalla distribuzione e dal servizio orario installato.
Non confondere la visualizzazione del fuso orario con uno sfasamento dell’orologio. Un host configurato con un fuso orario locale può mostrare un’ora diversa da quella UTC, pur indicando lo stesso istante corretto. Confronta i valori UTC o i timestamp Unix, non solo l’ora mostrata dall’orologio del desktop.
Di norma, i container condividono l’orologio di sistema dell’host anziché avere un orologio indipendente, ma il comportamento dipende dalla piattaforma e dall’ambiente di esecuzione. Controlla anche il nodo o la macchina virtuale che esegue il container. Negli ambienti di orchestrazione, individua il worker specifico che ha gestito la richiesta non riuscita: controllare un altro nodo potrebbe dare un risultato regolare senza spiegare l’incidente.
Verifica la presenza di uno sfasamento misurabile e lo stato della sincronizzazione, non limitarti a constatare che la data sembri plausibile. Anche un orologio sfasato di qualche secondo può bastare a causare il rifiuto di un timestamp, a seconda dell’intervallo consentito per la richiesta e delle condizioni di rete.
4. Ripristina la sincronizzazione dell’ora sull’host effettivamente usato
Usa il servizio di sincronizzazione dell’ora supportato dall’host: se devi sincronizzare orologio server per API Binance, controlla il servizio configurato sulla macchina che esegue il bot. Su un sistema gestito con systemd, controlla systemd-timesyncd o l’alternativa configurata, ad esempio Chrony; non dare per scontato che, attivando un servizio, questo diventi automaticamente la fonte oraria in uso. Dopo aver applicato la configurazione normale dell’host, controlla lo stato del servizio e la sincronizzazione segnalata.
Su una VM cloud, verifica che il servizio orario del sistema guest funzioni con la fonte oraria consigliata dal provider. Se la VM è stata sospesa, ripresa, migrata o ripristinata da uno snapshot, ricontrolla l’orologio prima di riattivare il bot. In alcuni ambienti l’ora viene corretta gradualmente: un processo avviato subito dopo un forte salto dell’orologio potrebbe quindi continuare a firmare le richieste in modo errato per un breve periodo.
Se usi un container, ripristina la sincronizzazione sull’host o sul nodo di orchestrazione anziché cercare di impostare l’orologio del container. In genere i container non hanno i permessi per modificare l’ora di sistema e concedere tali permessi a un bot di trading non è una soluzione sensata. Una volta ripristinata la sincronizzazione, verifica che l’host effettivamente usato riporti uno stato di sincronizzazione attiva: il solo fatto che il servizio sia «abilitato» non prova che abbia contattato una fonte oraria.
Riavvia il bot solo dopo aver controllato l’orologio dell’host. Poi ripeti la stessa richiesta di sola lettura e salva la risposta. Se l’errore persiste, confronta il timestamp della richiesta con l’ora del server Binance prima di modificare il codice che genera la firma.
5. Misura lo scarto rispetto all’ora del server Binance prima di firmare le richieste
Binance mette a disposizione un endpoint pubblico per controllare l’ora indicata dal server. Interrogalo subito prima o durante un test controllato e registra sia il timestamp del server sia l’ora locale prima e dopo la richiesta. In questo modo potrai confrontare direttamente l’ora del server con quella usata dal bot.
Il ritardo di rete influisce sul confronto. Per ottenere una stima approssimativa del punto medio, registra l’ora locale di invio e di ricezione, poi confronta l’ora restituita da Binance con il punto medio tra le due. Per esempio, se la richiesta parte all’ora locale t1 e torna all’ora t2, usa il punto medio tra t1 e t2 come stima approssimativa dell’ora locale in cui il server ha generato la risposta. Lo scarto risultante resta approssimativo, perché il percorso di rete potrebbe non essere simmetrico e il tempo di elaborazione dell’endpoint potrebbe non essere pari a zero.
Ripeti la misurazione più volte e privilegia una stima stabile basata su risposte con un tempo di andata e ritorno ridotto. Non considerare una singola risposta lenta come una lettura affidabile dell’orologio.
Se l’orologio dell’host differisce in modo significativo dalla stima basata sull’ora del server, ripristina prima la sincronizzazione. Uno scarto gestito a livello applicativo può aiutare a compensare differenze ridotte e misurate, ma non dovrebbe diventare un sostituto permanente di un servizio orario funzionante sull’host.
6. Gestisci in modo sicuro lo scarto e recvWindow
Se il bot ha bisogno di correggere lo scarto, calcola il valore in base a più misurazioni dell’ora del server e applicalo quando generi il timestamp firmato. Mantieni la correzione in memoria o in un valore di configurazione controllato, aggiornalo a intervalli regolari e registra lo scarto misurato e il timestamp usato per ogni richiesta non riuscita. Evita di codificare in modo permanente un valore ricavato da un singolo test: il ritardo di rete e le condizioni dell’host possono cambiare.
Applica la correzione prima di firmare. Il timestamp incluso nei parametri firmati deve coincidere con quello coperto dalla firma; modificarlo dopo aver generato la firma la rende non valida. Verifica la sequenza con un endpoint di sola lettura prima di consentire al bot di inviare ordini.
Un aumento contenuto di recvWindow può assorbire i normali ritardi di rete o piccole variazioni temporali, ma non corregge un orologio dell’host che è costantemente sfasato. Inoltre, un intervallo molto ampio può rendere accettabili le richieste ritardate più a lungo del previsto; mantieni quindi il valore più basso possibile, compatibilmente con la latenza misurata del bot e le regole dell’API.
Usa un solo meccanismo di correzione alla volta. Se l’orologio dell’host è sincronizzato e lo scarto misurato è prossimo allo zero, rimuovi le correzioni applicative non necessarie anziché sommare uno scarto basato sull’ora del server a un’altra correzione già applicata dalla libreria. Controlla come la libreria client gestisce i timestamp prima di aggiungere codice personalizzato.
7. Verifica il ripristino e previeni nuovi sfasamenti
Ripeti la stessa richiesta firmata di sola lettura e verifica che la risposta non contenga più -1021. Confronta il timestamp, lo scarto misurato rispetto all’ora del server e il tempo di andata e ritorno con quelli dell’errore iniziale. Solo a quel punto riprendi a gestire gli ordini, preferibilmente con una modalità di test o a basso rischio, se disponibile nella tua configurazione.
Registra il nome dell’host o del nodo, il timestamp locale, lo scarto misurato e il codice di errore dell’API. Imposta un avviso per le ripetute anomalie di timestamp, non per un singolo caso isolato: una serie di errori dopo un riavvio può indicare che la sincronizzazione non è ancora terminata, mentre gli errori ricorrenti su un solo nodo fanno pensare a un problema specifico dell’host.
Controlla di nuovo l’orologio dopo le sospensioni delle VM, i riavvii, le migrazioni dei container e i riavvii del servizio orario. Se gli errori ricompaiono dopo una modifica all’host, interrompi l’invio degli ordini e controlla il nodo che ha gestito la richiesta prima di aumentare recvWindow. Questo controllo può evitare che un orologio non aggiornato trasformi un problema temporaneo dell’infrastruttura in una serie di ordini rifiutati.
