Como corrigir o erro -1021 da API da Binance

Erro de timestamp -1021 da API da Binance: corrija o desvio do relógio em um bot de trading hospedado por você

Um bot de trading hospedado por você pode assinar uma solicitação corretamente e, ainda assim, ter a chamada rejeitada pela Binance. O erro -1021 indica um problema de timestamp: o horário da solicitação assinada está fora do intervalo aceito pela Binance ou adiantado em relação ao horário do servidor. A solução geralmente começa na máquina que executa o bot — não no código da estratégia. Se você está pesquisando como corrigir erro -1021 da API da Binance, comece verificando o relógio do ambiente de execução, em vez de alterar a lógica de trading.

Faça uma alteração de cada vez. Primeiro, registre a falha; depois, confira o relógio do ambiente de execução, restabeleça a sincronização de horário e só então ajuste o tratamento de timestamps ou o recvWindow. Essa ordem ajuda a evitar que um intervalo maior para as solicitações mascare um problema no relógio do host.

1. Confirme se -1021 é um erro de desvio do relógio

Leia o corpo completo da resposta, não apenas o status HTTP ou uma linha de log abreviada. O código e a mensagem de erro da API da Binance devem indicar que o timestamp está fora do intervalo permitido ou adiantado em relação ao horário do servidor.

Essa resposta é diferente de uma assinatura malformada, de uma chave de API ausente ou de uma falha de permissões. Esses problemas geralmente geram outros códigos ou mensagens de erro da API. Se o código for -1021, comece verificando o timestamp assinado, o relógio do servidor e o recvWindow configurado; não altere as chaves nem as permissões de trading como primeira reação. Para entender a função desse parâmetro, veja também o que é recvWindow na API da Binance: ele define uma janela de validade para solicitações, mas não corrige um relógio do host persistentemente incorreto.

Confirme também se a chamada que falha é assinada. As solicitações públicas de dados de mercado podem não usar o mesmo fluxo de autenticação, enquanto os endpoints de conta e de ordens normalmente exigem solicitações assinadas. Se o bot falha apenas nas chamadas assinadas, isso é uma pista útil.

2. Reproduza a falha com uma única solicitação assinada

Pause o envio de ordens antes de investigar. Use um endpoint assinado mínimo e somente de leitura, ao qual sua chave de API tenha permissão de acesso. Assim, você evita criar ou cancelar ordens enquanto coleta evidências. Se a chave não tiver acesso a esse endpoint, use outro endpoint somente de leitura compatível com a versão da API da Binance usada pelo bot.

Registre o timestamp exato da solicitação, o endpoint, o status da resposta, o código e a mensagem de erro da Binance, além do horário em que a solicitação saiu do processo. Oculte dos logs a chave de API, a assinatura, os dados da conta e quaisquer outros segredos. Nunca publique uma URL assinada ou um cabeçalho de autenticação completo em um fórum ou chat público.

Mantenha a reprodução simples.

Execute o teste no mesmo ambiente de processo em que ocorreu o erro. O shell do host pode ter o relógio correto, enquanto um contêiner, uma máquina virtual ou um worker usa uma configuração de execução diferente. Se uma solicitação somente de leitura funcionar após o ajuste do relógio, compare o timestamp e a resposta com os dados da falha registrada antes de reiniciar o ciclo completo de trading.

3. Compare o relógio do host com uma fonte de horário confiável

Confira o horário UTC e o estado da sincronização na máquina ou no host do contêiner que realmente executa o bot. No Linux, comandos como date -u e timedatectl status podem mostrar o horário UTC exibido e se a sincronização do relógio do sistema está ativa. Os comandos disponíveis dependem da distribuição e do serviço de horário instalado.

Não confunda a exibição do fuso horário com o desvio do relógio. Um host configurado para um fuso horário local pode mostrar uma hora diferente da hora UTC e, ainda assim, representar o instante correto. Compare valores UTC ou timestamps Unix, não apenas a hora mostrada pelo relógio da interface gráfica.

Em geral, os contêineres compartilham o relógio do sistema do host, em vez de manterem um relógio independente, mas o comportamento depende da plataforma e do ambiente de execução. Confira também o nó ou a máquina virtual que executa o contêiner. Em ambientes de orquestração, identifique o worker específico que processou a solicitação com falha; verificar outro nó pode dar um resultado normal sem explicar o incidente.

Procure medir o desvio e verificar o estado da sincronização, em vez de confiar apenas em uma data aparentemente plausível. Um relógio com alguns segundos de diferença pode ser suficiente para provocar a rejeição do timestamp, dependendo do intervalo da solicitação e das condições da rede.

4. Corrija a sincronização de horário no host que executa o bot

Use o serviço de sincronização de horário compatível com o host. Em um sistema gerenciado com systemd, verifique o systemd-timesyncd ou a alternativa configurada, como o Chrony; não presuma que ativar um serviço significa que ele é a fonte de horário em uso. Após aplicar a configuração padrão do host, confira o estado do serviço e o status de sincronização informado.

Em uma máquina virtual na nuvem, confirme se o serviço de horário do sistema convidado está funcionando com a fonte recomendada pelo provedor. Se a máquina virtual foi pausada, retomada, migrada ou restaurada a partir de um snapshot, confira novamente o relógio antes de colocar o bot em operação. Alguns ambientes corrigem o horário gradualmente, então um processo iniciado logo após um grande salto no relógio ainda pode assinar solicitações incorretamente por algum tempo.

Se estiver usando um contêiner, corrija a sincronização no host ou no nó de orquestração, em vez de tentar ajustar o relógio do contêiner. Em geral, os contêineres não têm permissão para alterar o horário do sistema, e conceder essa permissão a um bot de trading não é uma solução adequada. Depois de restabelecer a sincronização, confirme que o host usado pelo ambiente de execução está sincronizado; o simples fato de o serviço estar “ativado” não prova que ele tenha se conectado a uma fonte de horário.

Reinicie o bot somente depois de verificar o relógio do host. Em seguida, faça novamente a mesma solicitação somente de leitura e salve a resposta. Se o erro persistir, compare o timestamp da solicitação com o horário do servidor da Binance antes de alterar o código de assinatura do bot.

5. Meça o desvio em relação ao horário do servidor da Binance antes de assinar as solicitações

A Binance oferece um endpoint público de horário do servidor para consultar o horário informado por ela. Faça a consulta imediatamente antes ou durante um teste controlado e registre o timestamp do servidor e o horário local antes e depois da solicitação. Isso permite comparar diretamente o horário do servidor com o relógio usado pelo bot.

A latência da rede afeta essa comparação. Uma estimativa simples pelo ponto médio consiste em registrar o horário local de envio e de recebimento e, em seguida, comparar o horário retornado pela Binance com o ponto médio entre eles. Por exemplo, se a solicitação sai no horário local t1 e retorna em t2, use o ponto médio entre t1 e t2 como estimativa aproximada do horário local no momento em que o servidor gerou a resposta. O desvio resultante é aproximado, pois o caminho da rede pode ser assimétrico e o tempo de processamento do endpoint não é necessariamente zero.

Repita a medição várias vezes e prefira uma estimativa estável, baseada em respostas com baixa latência de ida e volta. Não considere uma única resposta demorada como uma leitura confiável do relógio.

Se houver uma diferença significativa entre o relógio do host e a estimativa do horário do servidor, corrija primeiro a sincronização. Um ajuste de horário no nível da aplicação pode ajudar a compensar pequenas diferenças medidas, mas não deve se tornar um substituto permanente para um serviço de horário funcional no host.

6. Adote uma estratégia segura de ajuste de horário e recvWindow

Se o bot precisar de uma correção de desvio, calcule-a com base em medições repetidas do horário do servidor e aplique-a ao gerar o timestamp assinado. Mantenha a correção em memória ou em um valor de configuração controlado, atualize-a periodicamente e registre o desvio medido e o timestamp usado em cada solicitação com falha. Evite fixar no código um valor copiado de um único teste: a latência da rede e as condições do host podem mudar.

Aplique a correção antes de assinar. O timestamp incluído nos parâmetros assinados precisa ser o mesmo timestamp coberto pela assinatura; alterá-lo depois de gerar a assinatura a invalida. Teste essa sequência com um endpoint somente de leitura antes de permitir que o bot envie ordens. Se a dúvida for como sincronizar o relógio de um bot da Binance, priorize a sincronização do host e use a correção no nível da aplicação apenas como complemento baseado em medições.

Um pequeno aumento no recvWindow pode acomodar a latência normal da rede ou pequenas variações de horário. Isso não corrige um relógio do host persistentemente errado. Um intervalo muito grande também pode fazer com que solicitações atrasadas sejam aceitas por mais tempo do que o desejado. Portanto, mantenha o valor tão baixo quanto a latência medida do bot e as regras da API permitirem.

Use apenas um mecanismo de correção por vez. Se o relógio do host estiver sincronizado e o desvio medido for próximo de zero, remova ajustes desnecessários no nível da aplicação em vez de somar uma correção baseada no horário do servidor a outra já feita pela biblioteca. Verifique como a biblioteca cliente trata timestamps antes de adicionar código personalizado.

7. Teste a recuperação e evite novos desvios no relógio

Repita a mesma solicitação assinada somente de leitura e confirme que a resposta não contém mais -1021. Compare o timestamp, o desvio medido em relação ao horário do servidor e a latência de ida e volta com os dados da falha anterior. Só então retome o processamento de ordens, de preferência em um modo de teste ou de baixo risco, se sua configuração permitir.

Registre o nome do host ou do nó, o timestamp local, o desvio medido e o código de erro da API. Gere um alerta se os erros de timestamp se repetirem, em vez de reagir a um único caso isolado. Uma sequência de erros após uma reinicialização pode indicar que a sincronização ainda não terminou, enquanto falhas recorrentes em um único nó sugerem um problema específico daquele host.

Confira o relógio novamente após pausas ou reinicializações de máquinas virtuais, migrações de contêineres e reinícios do serviço de horário. Se os erros voltarem após uma mudança de host, interrompa o envio de ordens e inspecione o nó que processou a solicitação antes de aumentar o recvWindow. Essa verificação pode impedir que um relógio desatualizado transforme um problema temporário de infraestrutura em uma sequência de ordens rejeitadas.