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.
Pontos-chave
- Quando você adiciona uma chave, a Freya verifica que ela conecta e tem as permissões certas antes de salvá-la — se algo falhar, o erro diz o que corrigir.
- “Chave/Secret API Inválido” geralmente significa um deslize de copiar/colar ou uma chave que foi regenerada; erros de “IP” significam que a restrição de IP da chave não corresponde ao que a Freya precisa.
- Sua chave precisa ter permissões de leitura e trading (nunca de saque) e estar habilitada para o mercado certo — spot ou futures — para corresponder ao seu bot.
- Chaves OKX exigem uma passphrase que precisa corresponder exatamente; para chaves de futures, a Freya prepara automaticamente sua conta para que o bot possa operar corretamente.
- Uma “Falha na Conexão” genérica geralmente é uma instabilidade momentânea de rede ou da exchange — basta tentar de novo.
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
- Recrie a chave na exchange com apenas leitura + trading (nunca saque).
- Restrinja-a ao IP que a Freya mostra na tela Adicionar Chave API.
- Combine o mercado — chave de spot para um bot de spot, chave de futures para um bot de futures.
- OKX: insira a passphrase exata.
- 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.