Come risolvere gli errori di connessione della chiave API per i bot di trading di criptovalute

Quando un bot di trading di criptovalute non riesce a connettersi a Binance o OKX, il messaggio visualizzato potrebbe essere generico come "autenticazione fallita" o "chiave API non valida". Questo messaggio non significa necessariamente che la chiave stessa sia errata. L'errore può derivare da problemi di autorizzazioni, da una lista di indirizzi IP consentiti, da un endpoint di prodotto non corrispondente, da una firma non valida, da un orologio non sincronizzato o da un limite di richieste.

Questa guida utilizza un esempio puramente ipotetico. Si tratta di un esempio puramente illustrativo, non di un test, risultato o testimonianza reale: Maya ha creato un bot per il trading spot e riceve un errore di connessione dopo aver inserito le credenziali di un account di scambio. La procedura di risoluzione dei problemi descritta di seguito mostra come potrebbe isolare la causa senza rivelare le sue credenziali o concedere un accesso non necessario all'account. L'interfaccia dell'exchange, il fornitore del bot e la formulazione del messaggio di errore potrebbero variare.

Cosa bisogna fare prima di cambiare la chiave API?

Metti in pausa il bot e impedisci i tentativi automatici mentre indaghi. Le richieste fallite ripetute possono rendere più difficile distinguere un problema di limitazione della frequenza delle richieste da un problema di autenticazione. Salva il testo esatto dell'errore, lo stato HTTP, il nome dell'exchange, il tipo di prodotto, l'endpoint (se visualizzato dal bot) e l'ora dell'errore. Non incollare mai una chiave segreta API, una passphrase, una richiesta firmata o un'intestazione di autorizzazione completa in un problema pubblico, una chat, uno screenshot o un ticket di supporto.

Una chiave API identifica l'integrazione. Il segreto API è il valore privato utilizzato per firmare le richieste, mentre la passphrase API è una credenziale aggiuntiva richiesta da alcuni exchange, tra cui OKX. Trattate tutti questi dati come sensibili. Se un segreto è stato compromesso, revocate la chiave e createne una nuova tramite l'interfaccia ufficiale dell'exchange prima di procedere.

A quale famiglia di errori appartiene questo messaggio?

Iniziate con la classificazione anziché con modifiche casuali. Gli errori di autenticazione e autorizzazione di solito indicano problemi con le credenziali, le autorizzazioni, le restrizioni IP o la firma. Gli errori di orario riguardano l'orologio di sistema o il timestamp della richiesta. Gli errori di rete e di limitazione della frequenza richiedono un approccio diverso: verificate la raggiungibilità, rallentate le richieste e accertatevi che un ordine precedente non sia stato accettato prima di riprovare.

Questi codici e messaggi sono riferimenti documentati, non garanzie che ogni bot li visualizzerà senza modifiche. Un bot di terze parti potrebbe tradurre, abbreviare o adattare la risposta dello scambio.

Come si verificano lo stato e le autorizzazioni di una chiave API?

Apri la pagina di gestione API dell'exchange direttamente dal sito web o dall'app ufficiale. Verifica che la chiave sia attiva, appartenga all'account o al sottoconto desiderato e sia destinata al prodotto che il bot utilizzerà. Una chiave creata per un ambiente o un account potrebbe non funzionare per un altro.

Utilizzare il principio del minimo privilegio. Un bot che legge solo i saldi necessita dell'accesso in lettura. Un bot che effettua e annulla ordini spot necessita dell'autorizzazione di trading dell'exchange. I prelievi sono una funzionalità separata e dovrebbero rimanere disabilitati a meno che non vi sia una ragione specifica e ben definita per abilitarli. Una connessione riuscita non dimostra che il bot possa effettuare ordini e un errore di autorizzazione durante un test di ordine non significa automaticamente che le credenziali non siano valide.

Nell'esempio ipotetico, Maya verifica innanzitutto se il suo bot è configurato per il trading spot, mentre la chiave è stata creata con solo accesso in lettura. Annota l'autorizzazione necessaria dalla documentazione del bot, abilita solo tale autorizzazione se applicabile, salva la modifica e attende che l'exchange la applichi. Non abilita i prelievi solo per far superare il test di connessione.

È possibile che una whitelist di indirizzi IP stia bloccando il bot?

Una whitelist IP, detta anche lista IP consentita, limita l'utilizzo delle API agli indirizzi sorgente approvati. Migliora la sicurezza, ma può bloccare una chiave perfettamente valida se il bot viene eseguito da un server cloud, un container, una connessione domestica o un provider il cui IP in uscita è cambiato. Chiedi al fornitore del bot l'indirizzo o gli indirizzi IP di uscita esatti. Non fare supposizioni basandoti sull'IP pubblico del tuo laptop per capire se il bot viene effettivamente eseguito altrove.

Confronta l'indirizzo fornito dal provider con la lista di indirizzi consentiti (allowlist) dell'exchange. Verifica se l'indirizzo IPv4 è diverso da quello IPv6, la presenza di spazi o voci obsolete e se la chiave è associata all'account corretto. Se il provider utilizza un intervallo di indirizzi a rotazione, chiedi se offre un indirizzo IP di uscita stabile. Non disabilitare la lista di indirizzi in modo permanente come soluzione rapida; se la rimuovi temporaneamente per una diagnosi controllata, ripristinala immediatamente e ruota la chiave se la modifica ha evidenziato un'integrazione sensibile.

La chiave, il segreto e la passphrase provengono dalla stessa integrazione?

Copia nuovamente le credenziali senza aggiungere spazi, virgolette, interruzioni di riga o caratteri nascosti. Verifica che la chiave API e il segreto siano stati generati come un'unica coppia. Su OKX, conferma anche l'esatta passphrase inserita al momento della creazione della chiave. La passphrase non è la stessa della password di accesso all'account e l'exchange specifica che una passphrase smarrita non può essere recuperata; è necessario un nuovo set di chiavi.

Verifica l'exchange selezionato nel bot. Una chiave Binance non può autenticare una richiesta OKX e una chiave dell'account principale potrebbe non rappresentare il sottoconto che intendevi utilizzare per le operazioni. Se non sei sicuro di quale valore sia stato incollato in quale campo, revoca la chiave incerta e crea una nuova coppia di valute anziché testare ripetutamente credenziali sconosciute.

Come si verificano gli errori di firma e di timestamp?

Le richieste API private non vengono autenticate inviando il segreto in chiaro. Il client crea un payload di firma preciso e genera una firma. Anche una singola discrepanza, come un ordine dei parametri modificato, una differenza nella codifica dell'URL, un metodo HTTP errato, un segreto errato o un corpo della richiesta alterato, può invalidarla.

Per le richieste REST di Binance Spot, la documentazione ufficiale descrive la firma HMAC-SHA-256 per le chiavi HMAC e richiede un timestamp sulle richieste firmate. La documentazione spiega anche recvWindowla finestra temporale consentita. Il riferimento attuale mostra un valore di esempio di cinque secondi, ma le impostazioni di un bot e i limiti dell'exchange possono variare; utilizzare il valore supportato dall'endpoint ed evitare di mascherare un problema di orologio con una finestra temporale inutilmente ampia.

Le richieste REST private di OKX utilizzano intestazioni che includono OK-ACCESS-KEY, OK-ACCESS-SIGN, OK-ACCESS-TIMESTAMP, e OK-ACCESS-PASSPHRASE. OKX descrive un pre-hash creato da timestamp, metodo HTTP, percorso della richiesta e corpo, seguito da codifica HMAC-SHA-256 e Base64. Specifica inoltre l'ora UTC ISO 8601 con precisione al millisecondo e consiglia la sincronizzazione con il suo endpoint orario pubblico. Assicurati che l'orologio del bot, il metodo HTTP, il percorso, i parametri di query e il corpo corrispondano a quanto firmato.

Nel thread ipotetico di Maya, il bot registra una firma non valida anziché un'autorizzazione rifiutata. Confronta il metodo di firma documentato dal fornitore del bot con l'exchange selezionato, verifica che il segreto non sia stato troncato, sincronizza l'orologio del server con l'UTC e testa un endpoint di lettura autenticato innocuo. Se il fornitore gestisce la firma internamente, fornisce solo le credenziali sostitutive tramite il campo segreto protetto e chiede al fornitore di esaminare i log oscurati.

Il bot sta utilizzando l'ambiente e l'endpoint del prodotto corretti?

Separa gli ambienti di "produzione" o mainnet da quelli di "testnet" o demo. Una chiave creata per un ambiente potrebbe non essere valida per l'altro. Distingui inoltre gli endpoint per spot, margin, future e opzioni. La stessa coppia di criptovalute può avere simboli, permessi, modalità di account e regole di ordine diversi a seconda del prodotto.

Leggi la guida all'integrazione del bot con gli exchange e confronta l'URL di base, il selettore di prodotto, il tipo di account, il formato del simbolo e la modalità WebSocket o REST con la documentazione attuale dell'exchange. Se il bot offre integrazioni separate per Binance Spot e Futures, scegli quella che corrisponde alla chiave e alla strategia. Non passare mai a un endpoint di produzione solo perché le credenziali di testnet non hanno funzionato.

La connessione potrebbe non funzionare a causa di limiti di velocità o problemi di rete?

Una volta verificate le credenziali, esaminate il modello di richiesta. Un bot che interroga con troppa frequenza saldi, ordini aperti e dati di mercato può raggiungere i limiti anche quando tutte le firme sono valide. Binance documenta -1003 TOO_MANY_REQUESTSe raccomanda l'utilizzo di flussi WebSocket per gli aggiornamenti in tempo reale, ove appropriato. OKX documenta 50011il raggiungimento del limite di frequenza e osserva che i limiti variano a seconda dell'endpoint e possono essere basati sull'indirizzo IP o sull'ID utente.

Riduci i polling duplicati, aggiungi un backoff esponenziale, limita i tentativi ed evita di avviare più istanze del bot con la stessa integrazione. Un timeout non è la prova che un ordine sia fallito: controlla lo stato dell'ordine prima di inviarne uno duplicato. Verifica anche il DNS, le regole del firewall, l'accesso HTTPS in uscita, le impostazioni del proxy, l'intercettazione TLS e se l'endpoint di scambio è disponibile nella tua regione o per il tuo account.

Qual è il modo più sicuro per ripetere il test dopo una riparazione?

1. Salva esattamente la modifica apportata, ad esempio la correzione dell'elenco IP consentiti o la selezione di Spot.
2. Utilizza prima una richiesta autenticata di sola lettura, ad esempio per verificare le informazioni del conto o il saldo.
3. Conferma che il bot segnali l'account e il prodotto desiderati, senza mostrare informazioni riservate.
4. Se è necessario effettuare un test degli ordini, utilizzare la dimensione minima praticabile e un mercato controllato solo dopo aver compreso le conseguenze, le commissioni e la modalità di gestione del conto.
5. Esamina i log per individuare codici di stato oscurati, timestamp, nomi degli endpoint e numero di tentativi.
6. Se l'errore persiste dopo aver verificato i parametri di base, o se la chiave potrebbe essere stata copiata in un servizio non attendibile, interrompere la procedura e ruotare la chiave.

Quali errori bisogna evitare?

• Non pubblicare né inviare tramite e-mail il segreto dell'API, nemmeno quando si richiede assistenza per il debug.
• Non abilitare i prelievi come soluzione rapida in caso di errore di autenticazione.
• Non aggiungere un intervallo di indirizzi IP ampio o sconosciuto a una lista di indirizzi consentiti solo per evitare un errore.
• Non riprovare a eseguire un ordine incerto alla cieca dopo un timeout; verificane prima lo stato.
• Non dare per scontato che una chiave sia valida per ogni prodotto di scambio, sottoconto, regione o ambiente.
• Non aumentare la frequenza di polling durante l'indagine su un errore.
• Non fidarti di una vecchia schermata di una pagina delle impostazioni di Exchange rispetto alla documentazione ufficiale aggiornata.

Riferimenti ufficiali e limiti di questa guida

Per il significato dei codici e i dettagli sulla firma, consultare il riferimento ai codici di errore dell'API Binance Spot e la documentazione dell'API REST di Binance Spot . Per l'autenticazione OKX, la sincronizzazione dell'ora, le autorizzazioni, i codici di errore e i limiti di frequenza, consultare la guida API di OKX . Questi documenti dei fornitori possono subire modifiche, pertanto si consiglia di rivederli quando il fornitore del bot rilascia un aggiornamento dell'integrazione.

Questo articolo è stato redatto sulla base delle fonti ufficiali disponibili al 16 settembre 2026. Descrive un metodo di diagnosi, non garantisce il funzionamento di un particolare bot, account di scambio, giurisdizione o versione API. Se l'exchange visualizza un messaggio relativo a sicurezza, conformità, blocco dell'account o disponibilità del prodotto, segui la procedura di supporto ufficiale dell'exchange e non tentare di aggirare la restrizione.