Erros comuns com as APIs da Binance

Durante o desenvolvimento e ensino de programação de bots para Binance eu fui tendo e ajudando a resolver diversos erros diferentes ligados às APIs da Binance. A ideia deste post é de servir como referência para tais erros e ajudar outros devs que estejam passando por algum deles.

Para erros HTTP comuns (400, 403, 500, etc), consulte este outro post genérico para status HTTP.

Para lista completa de erros de Spot, consulta a documentação oficial. Para lista completa de erros de Futuros, consulte a documentação oficial.

Use a busca do seu navegador (Ctrl+F) e procure por alguma palavra do seu erro para encontrar mais facilmente nesta página. Se estiver no grupo de alunos do meu curso no Telegram, use a pesquisa do grupo para encontrar respostas por lá também.

Erros envolvendo Chaves

Antes de qualquer erro, se você não souber como criar as suas chaves de teste e de produção corretamente, aprenda com o vídeo abaixo para Binance Spot. Mais adiante o vídeo para Binance Futures. Alguns alunos relataram não conseguirem criar as chaves na sua máquina seguindo as instruções abaixo, talvez por algum bloqueio ou restrição da Binance, e que resolveram usando outro computador e/ou outro IP.

Aqui o vídeo ensinando a criar as chaves para Binance Futures.

Erros com URLs Testnet x Produção

Muitos dos erros são causados por URLs inválidas, então abro este artigo trazendo as URLs de teste e produção para mercado Spot e Futuros. Para Spot, as URLs estão listadas aqui e para Futuros, estão listadas aqui. Repare que quando estiver apontando seu bot para Testnet, deve usar chaves de teste, caso contrário, chaves de produção.

Invalid API-Key, IP, or permissions for this action.

Este erro é quando você tenta acessar uma API privada, que exige autenticação e está com as chaves inválidas (basta recriar com as instruções dos vídeos anteriores) ou quando já está operando com as URLs de produção e não autorizou o IP da máquina onde está o seu robô na criação da API key. Ou ainda caso não tenha dados as permissões de spot nas chaves.

No caso de Futures precisa responder ao questionário da Binance antes de conseguir adicionar a permissão de futuros na sua chave de API, você responde ela na primeira vez que acessar a tela de trade de futuros (talvez tenha de mudar o idioma do site para acessar essa tela). E no caso da API de saque (withdraw) tem permissão específica a ser adicionada na chave também.

balanceData error

Este erro acontece quando tentamos conectar na API de carteira, para obter o saldo das moedas do usuário. Ele acontece quando suas chaves estão inválidas (basta recriar) ou quando o horário da sua máquina está errado, algo comum de estar errado no Windows. Muitos de meus alunos usam esta ferramenta para corrigir problemas de horário: Time Sync Tool enquanto que no Linux os comandos abaixo se mostraram úteis:

sudo apt-get install ntp ntpdate

sudo ntpdate pool.ntp.org

Signature for this request is not valid

Este erro acontece geralmente quando seu API secret está errado, mas pode ser alguma falha também na sua função de assinatura da requisição (HMAC-SHA).

Quando me refiro a API secret errado pode ser tanto ele estar informado errado, faltando caracteres, caracteres trocados ou ainda apenas não ser o secret para a API Key que foi informada na requisição. Também já vi acontecer por que o aluno usou chaves de Testnet Spot em Testnet Futuros, o que não funciona.

Invalid API Secret

Indica que sua API Secret é inválida ou ausente.

Api-key format invalid.

Indica que sua API Key é inválida ou ausente.

Service unavailable from a restricted location according to ‘b. Eligibility’ in https://www.binance.com/en/terms. Please contact customer service if you believe you received this message in error.

Essa mensagem indica que você está usando a API da Binance a partir de uma região na qual eles não possuem permissão para operar e por isso bloquearam sua chave. A Binance.com não pode operar nos EUA, por exemplo, lá eles possuem a BinanceUS, somente para americanos. Outros países que ela não pode operar inclui a China, a região de Ontario no Canadá e outros. Infelizmente eu não possuo a lista completa mas recordo que a partir do Brasil, da India e da Alemanha estava tranquilo de usar as APIs.

Unexpected Server Response: 451

O mesmo que o erro anterior. 451 é o código HTTP para Unavailable for Legal Reasos ou Indisponível por Motivos Legais.

Erros envolvendo Ordens

Filter Failure

Erros de filtro indicam que a sua ordem não está respeitando alguma regra da exchange. Ao lado do filter failure vai dizer qual regra. As regras completas de todos symbols pode ser encontrado na API exchangeInfo, basta acessar, salvar o JSON e procurar seu symbol nele.

Invalid quantity, Min. Lot Size, MIN_LOT_SIZE, LOT_SIZE ou Step Size

Todos erros contendo estas palavras são erros relativos ao parâmetro quantidade de uma ordem. Eles indicam que o valor enviado como quantidade não atende às regras de tamanho de lote (lot size) daquele par de moedas. Muitas vezes é o número exagerado de casas decimais que foi usado ou um tamanho inferior ao lote mínimo. As regras completas de lot size de todos symbols pode ser encontrado na API exchangeInfo, basta acessar, salvar o JSON e procurar seu symbol nele, vídeo mais abaixo explica tudo.

MIN_NOTIONAL, PRICE_FILTER, Min. Notional e Tick Size

Todos erros contendo estas palavras são erros relativos ao parâmetro preço de uma ordem. Eles indicam que o valor enviado como preço não atende às regras de preço nominal daquele par de moedas. Por exemplo, o valor mínimo de cada ordem não pode ser inferior a 10 USD em todos pares USD, USDT, etc. As regras completas de price de todos symbols pode ser encontrado na API exchangeInfo, basta acessar, salvar o JSON e procurar seu symbol nele. Vídeo abaixo explica tudo.

Ordem com status EXPIRED

Esse não é um erro de programação mas é comum de acontecer na Testnet com diversos pares de moedas. Como a Testnet não possui liquidez, uma vez que é um mercado só de devs operando com seus bots, muitos pares quando recebem uma ordem no book não tem como executá-la por não ter alguém disposto a comprar a sua ordem de venda ou vice-versa. Recomendo apenas testes usando o par BTCUSDT que é o que tem maior liquidez e menos chances de dar esse erro.

Order would immediately trigger ou Stop price would trigger immediately.

Este erro indica que o gatilho de preço que você definiu não faz sentido pois ele dispararia imediatamente. Caso queira disparar imediatamente uma ordem, use ordens a mercado. Caso deseje usar stops e limits, deve definir gatilhos de preço futuros, que não disparem imediatamente.

Retirado da documentação oficial da Binance:

• SELL: Limit Price > Last Price > Stop Price
• BUY: Limit Price < Last Price < Stop Price

Account has insufficient balance for requested action.

Esse erro indica que você não tem saldo suficiente para a ação. Se está tentando vender BTCUSDT, por exemplo, certifique-se de ter BTC suficiente para a venda que deseja. Se está comprando BTCUSDT por exemplo, certifique-se de ter USDT suficiente para a compra.

Geralmente quando os alunos tem esse erro é porque estão enviando informações erradas de quantidade ou realmente não tem saldo.

Precision is over the maximum defined for this asset.

Esse erro indica que está usando casas decimais demais na sua operação. As regras completas de precisão de todos symbols pode ser encontrado na API exchangeInfo, basta acessar, salvar o JSON e procurar seu symbol nele.

Not all sent parameters were read; read ‘6’ parameter(s) but was sent ‘7’.

Geralmente este erro vem associado com o código HTTP 400 (Bad Request) pois é justamente uma má formatação da sua request de envio de ordem. Os números 6 e 7 podem mudar, mas o que importa é entender que foi enviado mais parâmetros do que o necessário para essa requisição e/ou informado na assinatura. Neste caso o caminho é analisar com detalhe os parâmetros enviados na ordem para entender onde que você falou.

Erros envolvendo Streams

Web Socket Error: Closed, Reconnecting, ETIMEDOUT, EAI_AGAIN, ERR_SOCKET_CONNECTION_TIMEOUT, hang up, etc

Todos erros contendo estas palavras estão ligados a problemas de conectividade com as streams (websockets) da Binance. Junto ao erro tem a informação de qual stream ele tentou se conectar, então vale a pena verificar se está corretamente nomeada conforme documentação das streams. Caso esteja tudo programado corretamente, possivelmente é um problema de Internet do usuário ou alguma indisponibilidade temporária da Testnet (muito raro, somente durante manutenções).

Um último ponto neste item é com relação à versão do Node.js. Na data que escrevo este post a versão de Node recomendada é a 18 (LTS) e é muito comum a versão 20 ter problemas com streams/websockets, o que deve vir a ser corrigido quando ela se tornar estável (LTS).

Failed to construct WebSocket.

Esse erro é quando você está errando na construção da URL da stream.

userDataStream:subscribed:undefined

Indica que não conseguiu se conectar à stream de dados do usuário, possivelmente por problemas de credenciais ou de URL.

The URL scheme must be ws or wss. http is not allowed.

Isso quer dizer que a URL do seu websocket está errada, começando com HTTP.

Event isTrusted

Isso quer dizer que seu frontend perdeu a conexão com o websocket que ele estava conectado, possivelmente porque a conexão caiu do outro lado.

Invalid interval

Esse erro acontece em consultas de velas/candles. Um dos parâmetros necessários é o interval e se o valor passado for inválido, dará esse erro. Consulte a lista completa de parâmetros válidos na documentação oficial. Não consegue entender a documentação oficial? O vídeo abaixo explica.

Erros envolvendo ambiente e projeto

The property options.family must be one of: 0, 4, 6. Received false.

Este erro de DNS é causado em versões do Node.js superiores à 16, que é a recomendada em meus cursos. Não sei dizer ainda a causa, mas a solução é usar a versão 16.

Cannot find module…  e MODULE_NOT_FOUND

Não importa o módulo, se deu esse erro é porque você escreveu o nome dele errado, o caminho até ele errado (se for módulo próprio) ou esqueceu de instalar ele no projeto (se for módulo do NPM).

Timestamp for this request was 1000ms ahead of the server’s time.

Este erro indica que o horário da sua máquina está adiantado, problema comum no Windows, raro no Linux e inexistente no Mac até o momento. Muitos de meus alunos que usam Windows usaram esta ferramenta para corrigir problemas de horário: Time Sync Tool

Já no Linux, o relato que eu tenho de solução é usando esses comandos:

sudo apt-get install ntp ntpdate

sudo ntpdate pool.ntp.org

Timestamp for this request is outside of the recvWindow.

Outro erro ligado ao horário da sua máquina ou lentidão da sua Internet. Para resolver a questão do horário use a mesma dica anterior e opcionalmente aumenta a tolerância de atraso que por padrão é de 5000ms e pode ter até um máximo de 60000ms. O recvWindow é um parâmetro que você deve passar junto com os dados da sua request, como no exemplo abaixo, onde defini ao máximo.

Network Error e ERR_CONNECTION_REFUSED

O backend/API que está tentando acessar está fora do ar ou você informou o endereço errado.

…is not defined

Não importa o que venha antes, quer dizer que você tentou acessar uma propriedade de um objeto undefined, que está vazio, provavelmente problema na sua lógica.

EADDRINUSE ou address already in use

Sua máquina já está rodando um bot nesta mesma porta. Encerre a sua execução ou execute ele em outra porta.

DeprecationWarning

Isso não é um erro, é um aviso, mas causa confusão então vale explicar que esse aviso indica que algum pacote ou função caiu em desuso, mas ainda funciona. Recomenda-se mudar para um pacote ou função mais novos.

found x vulnerabilities

Isso não é um erro, é um aviso, mais causa confusão então vale explicar que esse aviso indica que algum pacote teve uma vulnerabilidade/falha de segurança encontrada. Recomenda-se mudar para um pacote mais novo ou mais seguro.

Query.run

Este é erro de mau uso do Sequelize e acontece quando o model que está sendo usado na consulta está diferente da tabela do banco de dados.

Access denied for user … using password: YES

Você errou o nome do usuário ou a senha do banco de dados.

Se o seu erro não está aqui, deixe nos comentários abaixo desse post. Outra excelente fonte para entender a documentação da Binance é esse vídeo abaixo.