Não Consegue Conectar Sua Exchange? Corrigindo Erros de Conexão da Chave API

#Não Consegue Conectar Sua Exchange? Corrigindo Erros de Conexão da Chave API

Quando você adiciona uma chave API de exchange, a Freya a verifica antes de salvar — e se algo estiver errado, ela diz o que corrigir. Este guia ajuda você a ler esse resultado e resolvê-lo. (Se sua chave já conectou normalmente mas um bot parou depois, isso é um problema diferente — veja Por Que Meu Bot Pausou ou Parou?.)

Para os passos de configuração inicial, comece com Como Conectar Sua Exchange; este artigo é sobre o que fazer quando essa conexão falha.

---

#Quando uma Chave Não Conecta

Adicionar uma chave não é um salvamento às cegas — a Freya verifica que a chave funciona e tem as permissões certas antes de armazená-la, criptografada. Se algo estiver errado, o erro aponta direto para a causa — geralmente a chave ou o secret, a restrição de IP ou uma permissão faltante. As seções abaixo percorrem cada erro e como corrigi-lo.

#"Chave API Inválida" ou "Secret Key Inválido"

O erro de conexão mais comum, e geralmente o mais simples:

• Um deslize de copiar/colar — um espaço perdido ou um caractere faltando. Recopie tanto a chave quanto o secret com cuidado.
• O secret é exibido apenas uma vez. As exchanges revelam o secret key uma única vez quando você o cria. Se você não o salvou, não pode recuperá-lo — crie uma nova chave.
• A chave foi deletada ou regenerada na exchange, então ela não corresponde mais.

Correção: insira novamente a chave e o secret exatamente, ou crie uma chave nova e tente de novo.

#Erros de Restrição de IP

A Freya conecta a partir dos seus próprios servidores, então as configurações de IP da chave importam. Há dois casos distintos:

• "IP Não Está na Whitelist" — sua chave é restrita por IP, mas o endereço do servidor da Freya não está na lista de permissões dela. A tela Adicionar Chave API mostra o(s) endereço(s) de IP a adicionar (com um botão de copiar) — adicione-os à whitelist da chave na exchange.
• "Sem Restrição" — sua chave não tem nenhuma restrição de IP. Para sua segurança, a Freya pede que você ative a restrição de IP e adicione o endereço que ela mostra, depois tente novamente.

Em ambos os casos a correção tem a mesma ideia: restrinja a chave ao IP que a Freya exibe na janela.

#Erros de Permissão

A chave conectou, mas não consegue fazer o que seu bot precisa:

• Leitura desativada — habilite a permissão de leitura/visualização na chave.
• Permissão de trading faltando — habilite o trading (spot e/ou futures, correspondendo ao seu bot).
• Incompatibilidade entre Spot e Futures — um bot de futures precisa de uma chave com trading de futures habilitado; um bot de spot precisa de trading de spot. Se você adicionou uma chave só de spot para um bot de futures (ou vice-versa), a Freya sinaliza isso. Garanta que o mercado habilitado da chave corresponda ao bot que você está criando.

Lembre-se: a Freya só precisa de permissões de leitura e trading — nunca de saque. Uma chave sem permissão de saque é exatamente o que você quer.

#Particularidades Específicas de Cada Exchange

• A OKX precisa de uma passphrase. Quando você cria uma chave OKX, você define uma passphrase — insira essa mesma passphrase na Freya, exatamente como você a definiu. Uma passphrase errada é uma falha de conexão comum na OKX.
• Configuração de futures na OKX. O trading de futures na OKX precisa de um modo de conta específico, que a Freya configura para você automaticamente — você não precisa configurá-lo manualmente.
• Hedge mode (futures). A Freya usa hedge mode para contas de futures. Se você já tem posições one-way abertas que entram em conflito, pode ver um aviso em vez de uma falha — a chave ainda é salva, e seu bot pode operar assim que essas posições existentes forem fechadas.
• Binance e Bybit não usam passphrase — não há campo de passphrase para elas.

#"Falha na Conexão" Sem Motivo Claro

Uma falha de conexão genérica geralmente não é culpa sua — uma instabilidade momentânea de rede ou a exchange estando brevemente sobrecarregada. Espere um momento e tente de novo. Se continuar falhando após algumas tentativas, reveja a chave/secret e as configurações de IP acima.

#Ainda Travado? Um Checklist Rápido

1. Recrie a chave na exchange com apenas leitura + trading (nunca saque).
2. Restrinja-a ao IP que a Freya mostra na tela Adicionar Chave API.
3. Combine o mercado — chave de spot para um bot de spot, chave de futures para um bot de futures.
4. OKX: insira a passphrase exata.
5. Ainda falhando? Entre em contato com [email protected].

#Perguntas Frequentes

#A Freya diz "Chave API Inválida" mas tenho certeza de que copiei corretamente — o que está errado?

Geralmente um caractere oculto ou espaço se infiltrou na chave ou no secret, ou a chave foi regenerada/deletada na exchange, então ela não corresponde mais. Recopie ambos os campos com cuidado, e lembre-se de que o secret é exibido apenas uma vez na criação — se você não o tem, crie uma chave nova.

#Qual é a diferença entre "IP Não Está na Whitelist" e "Sem Restrição"?

"IP Não Está na Whitelist" significa que sua chave é restrita por IP mas o endereço do servidor da Freya ainda não é permitido — adicione o endereço que a Freya mostra à whitelist da chave. "Sem Restrição" significa que a chave não tem nenhuma restrição de IP; por segurança, a Freya pede que você ative a restrição de IP e adicione o endereço dela antes de salvar.

#Minha chave OKX não conecta — preciso da passphrase?

Sim. Chaves OKX têm uma passphrase que você define ao criar a chave. Você precisa inserir essa passphrase exata na Freya — uma passphrase errada ou faltando é uma falha de conexão comum na OKX. Binance e Bybit não usam uma.

#A Freya diz que minha chave não pode realizar trades — como corrijo isso?

Sua chave não tem o trading habilitado para o mercado que seu bot usa. Na exchange, habilite a permissão de trading — trading de spot para um bot de spot, trading de futures para um bot de futures — depois reconecte. A Freya precisa de permissões de leitura e trading, nunca de saque.

#Minha chave de futures precisa de configuração extra (modo de conta / hedge mode) — isso é um problema?

Não. O trading de futures precisa de um modo de conta e hedge mode específicos, que a Freya configura para você automaticamente. Se você tem posições one-way existentes, pode ver um aviso de hedge mode em vez de um erro — a chave ainda é salva, e seu bot pode operar assim que essas posições forem fechadas.

#Adicionei uma chave de spot mas meu bot de futures não a usa (ou vice-versa) — por quê?

Uma chave é habilitada para um mercado específico. Um bot de futures precisa de uma chave com trading de futures habilitado, e um bot de spot precisa de trading de spot. Se eles não corresponderem, a Freya sinaliza. Conecte uma chave cujo mercado habilitado corresponda ao bot que você está criando.

#A conexão simplesmente "falhou" sem motivo claro — sou eu ou a exchange?

Frequentemente é uma instabilidade momentânea de rede ou da exchange, e não suas configurações. Tente de novo em um instante. Se continuar falhando, reveja a chave e o secret em busca de erros de cópia e confirme que a restrição de IP corresponde ao endereço que a Freya mostra.