Lorsque vous ajoutez une clé API d'exchange, Freya la vérifie avant de l'enregistrer — et si quelque chose ne va pas, il vous indique quoi corriger. Ce guide vous aide à lire ce résultat et à le corriger. (Si votre clé s'est bien connectée mais qu'un bot s'est arrêté plus tard, c'est un autre problème — voir Pourquoi mon bot s'est-il mis en pause ou arrêté ?.)
Pour les étapes de la première configuration, commencez par Comment connecter votre exchange ; cet article porte sur ce qu'il faut faire quand cette connexion échoue.
Points clés
- Lorsque vous ajoutez une clé, Freya vérifie qu'elle se connecte et dispose des bonnes permissions avant de l'enregistrer — si quelque chose échoue, l'erreur vous indique quoi corriger.
- « Clé/Secret API invalide » signifie généralement une erreur de copier-coller ou une clé qui a été régénérée ; les erreurs « IP » signifient que la restriction IP de la clé ne correspond pas à ce dont Freya a besoin.
- Votre clé doit avoir les permissions de lecture et de trading (jamais de retrait) et être activée pour le bon marché — spot ou futures — afin de correspondre à votre bot.
- Les clés OKX exigent une phrase secrète qui doit correspondre exactement ; pour les clés futures, Freya prépare automatiquement votre compte afin que le bot puisse trader correctement.
- Un « Échec de connexion » générique est souvent un accroc momentané du réseau ou de l'exchange — réessayez simplement.
Quand une clé refuse de se connecter
Ajouter une clé n'est pas un enregistrement à l'aveugle — Freya vérifie que la clé fonctionne et dispose des bonnes permissions avant qu'elle soit stockée, chiffrée. Si quelque chose ne va pas, l'erreur vous pointe directement vers la cause — généralement la clé ou le secret, la restriction IP, ou une permission manquante. Les sections ci-dessous passent en revue chaque erreur et comment la corriger.
« Clé API invalide » ou « Clé secrète invalide »
L'erreur de connexion la plus courante, et généralement la plus simple :
- Une erreur de copier-coller — un espace parasite ou un caractère manquant. Recopiez soigneusement la clé et le secret.
- Le secret n'est affiché qu'une seule fois. Les exchanges révèlent la clé secrète une seule fois lors de sa création. Si vous ne l'avez pas enregistrée, vous ne pouvez pas la récupérer — créez une nouvelle clé.
- La clé a été supprimée ou régénérée sur l'exchange, elle ne correspond donc plus.
Solution : ressaisissez exactement la clé et le secret, ou créez une nouvelle clé et réessayez.
Erreurs de restriction IP
Freya se connecte depuis ses propres serveurs, donc les réglages IP de la clé sont importants. Il y a deux cas distincts :
- « IP non autorisée » — votre clé est restreinte par IP, mais l'adresse du serveur Freya n'est pas sur sa liste blanche. L'écran d'ajout de clé API vous affiche la ou les adresses IP à ajouter (avec un bouton de copie) — ajoutez-les à la liste blanche de la clé sur l'exchange.
- « Sans restriction » — votre clé n'a aucune restriction IP du tout. Pour votre sécurité, Freya vous demande d'activer la restriction IP et d'ajouter l'adresse qu'il affiche, puis de réessayer.
Dans les deux cas, la solution repose sur la même idée : restreindre la clé à l'IP que Freya affiche dans la fenêtre.
Erreurs de permission
La clé s'est connectée, mais elle ne peut pas faire ce dont votre bot a besoin :
- Lecture désactivée — activez la permission de lecture/consultation sur la clé.
- Permission de trading manquante — activez le trading (spot et/ou futures, selon votre bot).
- Incohérence Spot / Futures — un bot futures a besoin d'une clé avec le trading futures activé ; un bot spot a besoin du trading spot. Si vous avez ajouté une clé spot uniquement pour un bot futures (ou l'inverse), Freya le signale. Assurez-vous que le marché activé sur la clé correspond au bot que vous créez.
Rappelez-vous : Freya n'a jamais besoin que des permissions de lecture et de trading — jamais de retrait. Une clé sans permission de retrait est exactement ce que vous voulez.
Pièges propres à chaque exchange
- OKX a besoin d'une phrase secrète. Lorsque vous créez une clé OKX, vous définissez une phrase secrète — saisissez cette même phrase secrète dans Freya, exactement comme vous l'avez définie. Une mauvaise phrase secrète est une cause fréquente d'échec de connexion sur OKX.
- Configuration futures OKX. Le trading futures OKX nécessite un mode de compte spécifique, que Freya configure pour vous automatiquement — vous n'avez pas besoin de le paramétrer manuellement.
- Mode hedge (futures). Freya utilise le mode hedge pour les comptes futures. Si vous avez déjà des positions ouvertes en mode one-way qui entrent en conflit, vous pourriez voir un avertissement plutôt qu'un échec — la clé est tout de même enregistrée, et votre bot peut trader une fois ces positions existantes clôturées.
- Binance et Bybit n'utilisent pas de phrase secrète — il n'y a pas de champ phrase secrète pour eux.
« Échec de connexion » sans raison claire
Un échec de connexion générique n'est souvent pas de votre faute — un accroc momentané du réseau ou l'exchange brièvement surchargé. Patientez un instant et réessayez. Si cela continue d'échouer après quelques tentatives, revérifiez la clé/le secret et les réglages IP ci-dessus.
Toujours bloqué ? Une checklist rapide
- Recréez la clé sur l'exchange avec lecture + trading uniquement (jamais de retrait).
- Restreignez-la à l'IP que Freya affiche dans l'écran d'ajout de clé API.
- Faites correspondre le marché — clé spot pour un bot spot, clé futures pour un bot futures.
- OKX : saisissez la phrase secrète exacte.
- Toujours en échec ? Contactez [email protected].
Questions fréquentes
Freya affiche « Clé API invalide » mais je suis sûr de l'avoir copiée correctement — qu'est-ce qui ne va pas ?
Généralement, un caractère ou un espace caché s'est glissé dans la clé ou le secret, ou la clé a été régénérée/supprimée sur l'exchange et ne correspond donc plus. Recopiez soigneusement les deux champs, et rappelez-vous que le secret n'est affiché qu'une seule fois à la création — si vous ne l'avez pas, créez une nouvelle clé.
Quelle est la différence entre « IP non autorisée » et « Sans restriction » ?
« IP non autorisée » signifie que votre clé est restreinte par IP mais que l'adresse du serveur Freya n'est pas encore autorisée — ajoutez l'adresse que Freya affiche à la liste blanche de la clé. « Sans restriction » signifie que la clé n'a aucune restriction IP du tout ; pour votre sécurité, Freya vous demande d'activer la restriction IP et d'ajouter son adresse avant d'enregistrer.
Ma clé OKX refuse de se connecter — ai-je besoin de la phrase secrète ?
Oui. Les clés OKX ont une phrase secrète que vous définissez lors de la création de la clé. Vous devez saisir cette phrase secrète exacte dans Freya — une phrase secrète erronée ou manquante est une cause fréquente d'échec de connexion sur OKX. Binance et Bybit n'en utilisent pas.
Freya dit que ma clé ne peut pas passer d'ordres — comment corriger cela ?
Votre clé n'a pas le trading activé pour le marché qu'utilise votre bot. Sur l'exchange, activez la permission de trading — trading spot pour un bot spot, trading futures pour un bot futures — puis reconnectez. Freya a besoin des permissions de lecture et de trading, jamais de retrait.
Ma clé futures nécessite une configuration supplémentaire (mode de compte / mode hedge) — est-ce un problème ?
Non. Le trading futures nécessite un mode de compte et un mode hedge spécifiques, que Freya configure pour vous automatiquement. Si vous avez des positions one-way existantes, vous pourriez voir un avertissement de mode hedge au lieu d'une erreur — la clé est tout de même enregistrée, et votre bot peut trader une fois ces positions clôturées.
J'ai ajouté une clé spot mais mon bot futures ne l'utilise pas (ou l'inverse) — pourquoi ?
Une clé est activée pour un marché précis. Un bot futures a besoin d'une clé avec le trading futures activé, et un bot spot a besoin du trading spot. S'ils ne correspondent pas, Freya le signale. Connectez une clé dont le marché activé correspond au bot que vous créez.
La connexion a simplement « échoué » sans raison claire — est-ce de mon fait ou de celui de l'exchange ?
C'est souvent un accroc momentané du réseau ou de l'exchange plutôt que vos réglages. Réessayez dans un instant. Si cela continue d'échouer, revérifiez la clé et le secret pour des erreurs de copie et confirmez que la restriction IP correspond à l'adresse que Freya affiche.