Cuando agregas una clave API de exchange, Freya la verifica antes de guardarla — y si algo no está bien, te dice qué corregir. Esta guía te ayuda a leer ese resultado y solucionarlo. (Si tu clave ya se conectó correctamente pero un bot se detuvo más tarde, ese es un problema diferente — consulta ¿Por Qué Mi Bot Se Pausó o Se Detuvo?.)
Para los pasos de configuración inicial, empieza con Cómo Conectar Tu Exchange; este artículo trata sobre qué hacer cuando esa conexión falla.
Puntos clave
- Cuando agregas una clave, Freya verifica que se conecte y tenga los permisos correctos antes de guardarla — si algo falla, el error te dice qué corregir.
- «Clave/Secreto API Inválido» normalmente significa un desliz al copiar/pegar o una clave que fue regenerada; los errores de «IP» significan que la restricción de IP de la clave no coincide con lo que Freya necesita.
- Tu clave debe tener permisos de lectura y de trading (nunca de retiro) y estar habilitada para el mercado correcto — spot o futuros — para coincidir con tu bot.
- Las claves de OKX requieren un passphrase que debe coincidir exactamente; para las claves de futuros, Freya prepara automáticamente tu cuenta para que el bot pueda operar correctamente.
- Un «Conexión Fallida» genérico suele ser un problema momentáneo de red o del exchange — simplemente vuelve a intentarlo.
Cuando una Clave No Se Conecta
Agregar una clave no es un guardado a ciegas — Freya verifica que la clave funcione y tenga los permisos correctos antes de almacenarla, cifrada. Si algo no está bien, el error te apunta directamente a la causa — normalmente la clave o el secreto, la restricción de IP, o un permiso faltante. Las secciones a continuación recorren cada error y cómo solucionarlo.
«Clave API Inválida» o «Clave Secreta Inválida»
El error de conexión más común, y normalmente el más simple:
- Un desliz al copiar/pegar — un espacio extraviado o un carácter faltante. Vuelve a copiar con cuidado tanto la clave como el secreto.
- El secreto se muestra solo una vez. Los exchanges revelan la clave secreta una única vez cuando la creas. Si no la guardaste, no puedes recuperarla — crea una clave nueva.
- La clave fue eliminada o regenerada en el exchange, así que ya no coincide.
Solución: vuelve a ingresar la clave y el secreto exactamente, o crea una clave nueva e inténtalo de nuevo.
Errores de Restricción de IP
Freya se conecta desde sus propios servidores, así que la configuración de IP de la clave importa. Hay dos casos distintos:
- «IP No Incluida en la Lista Blanca» — tu clave está restringida por IP, pero la dirección del servidor de Freya no está en su lista de permitidos. La pantalla de Agregar Clave API te muestra la(s) dirección(es) IP a agregar (con un botón de copiar) — agrégalas a la lista blanca de la clave en el exchange.
- «Sin Restricción» — tu clave no tiene ninguna restricción de IP. Por tu seguridad, Freya te pide que actives la restricción de IP y agregues la dirección que muestra, luego inténtalo de nuevo.
En ambos casos la solución parte de la misma idea: restringe la clave a la IP que Freya muestra en la ventana.
Errores de Permisos
La clave se conectó, pero no puede hacer lo que tu bot necesita:
- Lectura deshabilitada — habilita el permiso de lectura/visualización en la clave.
- Permiso de trading faltante — habilita el trading (spot y/o futuros, según tu bot).
- Desajuste entre Spot y Futuros — un bot de futuros necesita una clave con trading de futuros habilitado; un bot de spot necesita trading de spot. Si agregaste una clave solo de spot para un bot de futuros (o viceversa), Freya lo señala. Asegúrate de que el mercado habilitado de la clave coincida con el bot que estás creando.
Recuerda: Freya solo necesita permisos de lectura y trading — nunca de retiro. Una clave sin permiso de retiro es exactamente lo que quieres.
Particularidades Específicas de Cada Exchange
- OKX necesita un passphrase. Cuando creas una clave de OKX, defines un passphrase — ingresa ese mismo passphrase en Freya, exactamente como lo configuraste. Un passphrase incorrecto es una causa común de fallo de conexión en OKX.
- Configuración de futuros en OKX. El trading de futuros en OKX necesita un modo de cuenta específico, que Freya configura por ti automáticamente — no necesitas hacerlo manualmente.
- Modo hedge (futuros). Freya usa el modo hedge para las cuentas de futuros. Si ya tienes posiciones one-way abiertas que entran en conflicto, podrías ver una advertencia en lugar de un fallo — la clave igual se guarda, y tu bot puede operar una vez que esas posiciones existentes se cierren.
- Binance y Bybit no usan passphrase — no hay un campo de passphrase para ellos.
«Conexión Fallida» Sin una Razón Clara
Un fallo de conexión genérico a menudo no es culpa tuya — un parpadeo momentáneo de la red o el exchange estando brevemente ocupado. Espera un momento y vuelve a intentarlo. Si sigue fallando tras varios intentos, vuelve a revisar la clave/secreto y la configuración de IP descritos arriba.
¿Aún Atascado? Una Lista de Verificación Rápida
- Recrea la clave en el exchange con solo lectura + trading (nunca retiro).
- Restríngela a la IP que Freya muestra en la pantalla de Agregar Clave API.
- Haz coincidir el mercado — clave de spot para un bot de spot, clave de futuros para un bot de futuros.
- OKX: ingresa el passphrase exacto.
- ¿Sigue fallando? Contacta a [email protected].
Preguntas Frecuentes
Freya dice «Clave API Inválida» pero estoy seguro de que la copié correctamente — ¿qué está mal?
Normalmente un carácter oculto o un espacio se coló en la clave o el secreto, o la clave fue regenerada/eliminada en el exchange así que ya no coincide. Vuelve a copiar ambos campos con cuidado, y recuerda que el secreto se muestra solo una vez al crearlo — si no lo tienes, crea una clave nueva.
¿Cuál es la diferencia entre «IP No Incluida en la Lista Blanca» y «Sin Restricción»?
«IP No Incluida en la Lista Blanca» significa que tu clave está restringida por IP pero la dirección del servidor de Freya aún no está permitida — agrega la dirección que Freya muestra a la lista blanca de la clave. «Sin Restricción» significa que la clave no tiene ninguna restricción de IP; por seguridad, Freya te pide que actives la restricción de IP y agregues su dirección antes de guardar.
Mi clave de OKX no se conecta — ¿necesito el passphrase?
Sí. Las claves de OKX tienen un passphrase que defines al crear la clave. Debes ingresar ese passphrase exacto en Freya — un passphrase incorrecto o faltante es una causa común de fallo de conexión en OKX. Binance y Bybit no usan uno.
Freya dice que mi clave no puede realizar operaciones — ¿cómo lo soluciono?
Tu clave no tiene el trading habilitado para el mercado que usa tu bot. En el exchange, habilita el permiso de trading — trading de spot para un bot de spot, trading de futuros para un bot de futuros — luego vuelve a conectar. Freya necesita permisos de lectura y trading, nunca de retiro.
Mi clave de futuros necesita configuración adicional (modo de cuenta / modo hedge) — ¿es un problema?
No. El trading de futuros necesita un modo de cuenta específico y modo hedge, que Freya configura por ti automáticamente. Si tienes posiciones one-way existentes, podrías ver una advertencia de modo hedge en lugar de un error — la clave igual se guarda, y tu bot puede operar una vez que esas posiciones se cierren.
Agregué una clave de spot pero mi bot de futuros no la usa (o viceversa) — ¿por qué?
Una clave está habilitada para un mercado específico. Un bot de futuros necesita una clave con trading de futuros habilitado, y un bot de spot necesita trading de spot. Si no coinciden, Freya lo señala. Conecta una clave cuyo mercado habilitado coincida con el bot que estás creando.
La conexión simplemente «falló» sin una razón clara — ¿soy yo o el exchange?
A menudo es un problema momentáneo de red o del exchange en lugar de tu configuración. Inténtalo de nuevo en un momento. Si sigue fallando, vuelve a revisar la clave y el secreto en busca de errores de copiado y confirma que la restricción de IP coincida con la dirección que Freya muestra.