¿API Key no válida? Por qué aparece «API Key Data Are Invalid» y cómo solucionarlo

El error «invalid API key» es uno de los mensajes más engañosos en el trabajo con API, porque casi siempre la clave no tiene nada de malo. El problema casi siempre está en cómo se almacena, se carga o se enruta la clave, no en la clave en sí. Esta guía repasa una a una todas las causas habituales, te enseña a leer el error real que devuelve el proveedor (incluido el contenido exacto que devuelve HiAPI) y ofrece una lista de verificación que puedes copiar y pegar para validar la clave de extremo a extremo y no perder una tarde depurando la aplicación.

Por qué una clave que parece correcta sigue fallando

Estas son las causas de la gran mayoría de los errores de clave no válida, ordenadas aproximadamente por frecuencia, con su correspondiente solución.

Espacios en blanco o saltos de línea al principio o al final. Esta es la causa número uno y también la más difícil de detectar, porque al imprimir la clave parece normal. La trampa clásica es construir el .env con echo, que añade un \n final:

# Incorrecto: añade un salto de línea que pasa a formar parte del valor de la clave
echo "HIAPI_API_KEY=sk-..." >> .env
# Correcto: sin salto de línea final
printf 'HIAPI_API_KEY=sk-...\n' >> .env

Un salto de línea final o un espacio de más convierte Bearer sk-abc en Bearer sk-abc\n y el servidor lo rechaza. Solución: eliminarlo. En el shell: KEY="$(printf '%s' "$KEY" | tr -d '[:space:]')". En el código, usa key.strip() (Python) o key.trim() (JS) antes de construir la cabecera.

La clave está en la variable de entorno equivocada, o directamente no se carga. Tu código lee HIAPI_API_KEY, pero tu shell exporta HIAPI_KEY. O la variable está definida en tu shell interactivo, pero el proceso (una tarea cron, un contenedor Docker, un runner de CI) nunca la hereda. Solución: imprime lo que el proceso ve realmente antes de la llamada —echo "${HIAPI_API_KEY:0:6}…"— y confirma que el nombre de la variable coincide con el que lee el código.

La clave está revocada, rotada o caducada. Alguien rotó la clave, un compañero de equipo regeneró la clave, o la clave se filtró en un repositorio público y se revocó automáticamente. El valor antiguo ya no sirve. Solución: genera una clave nueva en la consola y sustituye todas las copias de la clave antigua.

Envías la clave al servicio equivocado. Enviar una clave de OpenAI a HiAPI, o una clave de HiAPI a OpenAI, siempre será rechazado, porque el servicio receptor no emitió esa clave. Confirma que la clave y el endpoint pertenecen al mismo servicio. Las solicitudes de generación de HiAPI usan https://api.hiapi.ai/v1/tasks y una clave de HiAPI.

Falta el esquema Bearer o está mal formado. La cabecera debe ser Authorization: Bearer sk-... — es decir, la palabra Bearer, un espacio y después la clave. Enviar solo la clave desnuda, o Authorization: sk-..., o Bearer: sk-..., fallará. Solución: revisa la cadena exacta de la cabecera.

La clave se truncó al copiarla. Al copiar una clave larga desde una terminal estrecha, un mensaje de chat o un campo de UI con desplazamiento, se corta. Solución: compara la longitud y los últimos caracteres con la consola; usa el botón de copiar en lugar de seleccionar arrastrando.

La clave no tiene permisos para ese modelo o grupo. La clave es válida y se carga correctamente, pero no tiene permitido llamar al modelo concreto que solicitas. Es fácil malinterpretar esto como «clave no válida», cuando en realidad es un problema de alcance de permisos. Solución: concede a esa clave acceso a ese modelo, o usa una clave que ya tenga el permiso.

El error real de HiAPI (léelo, no lo adivines)

Cuando la autenticación falla en HiAPI, obtienes un HTTP 401 con el siguiente cuerpo de respuesta (verificado en pruebas reales):

{
  "error": {
    "code": "permission_denied",
    "type": "hiapi_error",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: 2026...Y7",
    "request_id": "2026...Y7"
  }
}

De aquí se extraen tres conclusiones:

1. El código de estado es 401 y el code es permission_denied. HiAPI no devuelve error_key_does_not_exist ni invalid_api_key; esas cadenas vienen de otros ecosistemas (OpenAI usa invalid_api_key; error_key_does_not_exist es la fórmula genérica de algunas pasarelas). Si vas a hacer coincidir códigos de error en HiAPI, hazlo con permission_denied.
2. El mensaje te indica que es un problema de clave/permisos, que se corresponde directamente con las dos causas anteriores: clave incorrecta/ausente, o una clave válida sin acceso a ese modelo. Primero vuelve a revisar la clave y después los permisos del modelo.
3. request_id es lo que debes proporcionar al equipo de soporte. No envíes capturas de pantalla de la terminal: cita el request_id. Permite al equipo de soporte localizar en sus registros la solicitud exacta que falló.

Lee siempre el cuerpo JSON de la respuesta, no solo el código de estado. Ambos servicios pueden devolver 401, pero la causa real está en el cuerpo de la respuesta.

Lista de verificación de configuración de la API Key

Antes de depurar el código de tu aplicación, ejecuta esta lista de arriba abajo para validar cualquier clave. Aísla la clave de tu framework, de la carga del entorno y del cliente HTTP.

1. Vuelve a copiar la clave usando el botón de copiar de la consola; nunca la selecciones manualmente.
2. Elimina los espacios en blanco. Da por hecho que hay un salto de línea final hasta que demuestres lo contrario.
3. Colócala en una variable de entorno, no en el código fuente: export HIAPI_API_KEY='sk-...'.
4. Confirma que el proceso la ve: echo "${HIAPI_API_KEY:0:6}…" debe imprimir tu prefijo.
5. Confirma que la URL base coincide con el proveedor; para HiAPI, es https://api.hiapi.ai.
6. Realiza una llamada de autenticación mínima (la API de tareas de HiAPI, más abajo).
7. Lee el cuerpo de la respuesta. Si devuelve taskId, la clave es válida. Si devuelve 401, vuelve a revisar los pasos 1–5; si devuelve permission_denied relativo a un modelo, la clave no tiene acceso a ese modelo.
8. Solo entonces conecta la aplicación. Si curl funciona y la aplicación no, el fallo está en la carga del entorno o en la construcción de la cabecera del código, no en la clave.

Llamada mínima a HiAPI del paso 6:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red apple on a white table"}}'

Si tiene éxito, devuelve un taskId; después consulta GET https://api.hiapi.ai/v1/tasks/<taskId> hasta que status sea success, y lee la URL de la imagen en data.output[0].url. Encontrarás todos los detalles en la documentación de HiAPI. Una vez validada la clave, puedes usarla con cualquier modelo; empieza por la página del modelo GPT Image 2 y cambia el campo model para cambiar de modelo.

Crear y rotar claves

Las claves están en la consola de HiAPI. Para crear una clave, inicia sesión y genera una nueva; cópiala de inmediato, porque el valor completo solo se muestra una vez. Para rotar sin tiempo de inactividad, crea primero la clave nueva, despliégala en todos los lugares donde se usaba la antigua, valídala con la lista de verificación anterior y después revoca la clave antigua. Rota las claves siempre que una pueda haberse filtrado, cuando un compañero de equipo se marche, o según el calendario de rotación de producción.

«claude code invalid api key»: la respuesta honesta

Si Claude Code informa de una invalid API key, el problema casi nunca está del lado de HiAPI, porque Claude Code se autentica contra Anthropic. Causas habituales:

• ANTHROPIC_API_KEY incorrecta, caducada o rotada. Anthropic devuelve para ello 401 con authentication_error / «invalid x-api-key». Solución: configura la clave actual de Anthropic.
• Ajustes heredados de sobrescritura de base-URL o proxy. Si ANTHROPIC_BASE_URL (o un ajuste de proxy personalizado) apunta a un lugar que no acepta tu clave, todas las llamadas se interpretarán como no válidas. Solución: elimina la sobrescritura, o asegúrate de que la clave coincide con el endpoint al que apunta.

HiAPI no arregla las claves de Anthropic ni de OpenAI; esas credenciales las emite y valida cada uno de sus servicios. Si tu aplicación usa HiAPI, llama a la API unificada de tareas con una clave de HiAPI. Cambiar solo la URL base no permite reutilizar la estructura de solicitud y respuesta de OpenAI.

Preguntas frecuentes

¿Por qué mi API key parece correcta pero se indica como no válida? Porque la causa rara vez es la cadena visible. Por orden de probabilidad: un salto de línea o espacio final (a menudo por usar echo en lugar de printf), que la clave esté en la variable de entorno equivocada o que el proceso no la cargue, que la clave se haya rotado/revocado, o que se envíe a la URL base equivocada. Ejecuta la lista de verificación anterior: el curl del paso 6 aísla la clave de la aplicación y, en una sola llamada, te dice si el problema está en la clave o en el código.

¿Cómo se soluciona la invalid API key en Claude Code? Configura la ANTHROPIC_API_KEY actual y elimina cualquier ANTHROPIC_BASE_URL o sobrescritura de proxy obsoleta. La autenticación de Claude Code no tiene relación con HiAPI. Para generar contenido multimedia con HiAPI, usa una clave de HiAPI y llama a POST https://api.hiapi.ai/v1/tasks.

¿Qué es error_key_does_not_exist? Es el mensaje genérico de «esta clave no se reconoce» que usan algunas pasarelas y ecosistemas de API; significa que el servidor no tiene registro de la clave que enviaste. No es un código de error de HiAPI; HiAPI devuelve permission_denied con HTTP 401. En la práctica, la solución es la misma: confirma que la clave es la actual, que no tiene espacios en blanco y que se envía a la URL base del proveedor correcto.

¿Cuál es la diferencia entre 401 y 403 aquí? 401 significa que la solicitud no superó la autenticación: la clave falta, está mal formada o no se reconoce. 403/las respuestas de tipo permisos significan que la autenticación se superó, pero no se permite esa operación concreta. HiAPI clasifica los casos de permisos insuficientes de la clave como 401 con permission_denied, así que lee el mensaje: si menciona un modelo, es un problema de alcance de permisos, no de que la clave no sea válida.

¿Hay una forma más rápida de probar la clave que montar la aplicación completa? Sí: el único curl de la lista de verificación. Si devuelve taskId, la clave es correcta y cualquier fallo restante está en la carga del entorno o en la construcción de la cabecera de la aplicación. Para conocer una ruta de nivel producción con crédito de registro gratuito que te permite probar generaciones reales antes de pagar, consulta generación de imágenes con IA gratis y sin necesidad de clave.