Datos de clave API no válidos: causas de este error y cómo solucionarlo

Cuando al llamar a hiapi ves un mensaje similar a "the api keys data are invalid" (o una variante parecida que genere tu aplicación), significa que la solicitud no ha superado la autenticación en absoluto. En el fondo, la propia API de hiapi devuelve para ello un error específico: HTTP 401, error.code: "permission_denied", con el mensaje "This API key is invalid. Check that it is correct or use another API key and try again." (Esta clave API no es válida. Comprueba que sea correcta o usa otra clave API e inténtalo de nuevo). Cualquier aplicación que envuelva hiapi —un proxy de backend, un cliente compatible con OpenAI, un SDK interno— vuelve a etiquetar ese mismo 401 con sus propias palabras, y por eso el texto exacto que ves rara vez coincide con el original de hiapi. Esta guía explica paso a paso por qué ocurre y cómo confirmarlo y solucionarlo en unos minutos.

Aspecto real del error

Una solicitud fallida a POST https://api.hiapi.ai/v1/tasks (o a cualquier otro endpoint de hiapi) devuelve:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: <id>",
    "request_id": "<id>",
    "type": "hiapi_error"
  }
}

El código de estado HTTP es 401. Si tu framework o SDK no expone la respuesta original, puede reempaquetarla en un mensaje genérico de «API key(s) data are invalid», «unauthorized» o «invalid credentials»; pero la causa raíz del lado de hiapi es siempre el mismo 401.

Causas habituales (de mayor a menor probabilidad)

1. El valor de la clave es incorrecto. Un copiar y pegar truncado, un espacio de más o haber copiado desde una nota antigua en lugar de la clave activa en Dashboard → API Keys desencadena exactamente este error: tanto si la clave está corrupta, vacía o simplemente no existe, el mensaje que devuelve hiapi es idéntico.
2. La clave de marcador de posición nunca se sustituyó. El código copiado de tutoriales o plantillas suele contener una cadena literal como sk-your-api-key: produce un 401 exactamente igual que una cadena aleatoria.
3. La clave se ha rotado o revocado. Crear una clave nueva en el panel no invalida automáticamente la anterior, pero revocarla o regenerarla manualmente sí; si algún despliegue sigue haciendo referencia al valor antiguo (una variable de entorno no redesplegada, un .env no recargado), todas las solicitudes darán 401.
4. La clave se envía en una cabecera incorrecta. hiapi solo lee la clave de la cabecera Authorization. Enviarla como x-api-key, api-key o como parámetro de consulta produce la misma respuesta permission_denied, porque en ese caso hiapi no ve una clave mal formada: simplemente no ve ninguna clave.
5. La variable de entorno de ejecución está vacía. Si tu proceso lee la variable de la clave antes de cargar el archivo .env, envía una cadena vacía como clave: de nuevo un 401.
6. Se han colado espacios ocultos o saltos de línea en la clave. Es muy traicionero: pasar un secreto por una tubería con echo en un script de shell añade un salto de línea al final del valor. Si acaba en la cabecera Authorization, rompe la solicitud de otra manera: no un 401 limpio, sino un 400 con un mensaje confuso de invalid json body, porque la cabecera dañada se filtra al cuerpo de la solicitud. Si tu error parece una solicitud mal formada en lugar de un limpio «invalid key», revisa primero si la clave tiene espacios en blanco o saltos de línea sueltos.

Corrección en orden

1. Abre Dashboard → API Keys y vuelve a copiar la clave. No reutilices valores del historial del terminal ni de mensajes antiguos: cópiala directamente de la página.
2. Confirma que el formato de la cabecera coincide exactamente: Authorization: Bearer YOUR_API_KEY. Si montas este valor en un script de shell, usa printf en lugar de echo: echo añade un salto de línea final que printf no añade.
3. Imprime el valor justo antes de enviar la solicitud (console.log, print o un log de depuración) para confirmar que no está vacío y que no tiene comillas, espacios ni saltos de línea sueltos.
4. Aísla la clave de tu aplicación con una llamada curl simple (ver más abajo). Si curl funciona y tu aplicación sigue fallando, el fallo está en cómo construye la solicitud tu aplicación, no en la clave.
5. Comprueba el código de estado HTTP exacto que recibes. 401 es este error. 402 significa que el saldo de la cuenta está vacío, no que la clave sea incorrecta. 403 significa que la clave es válida pero le faltan permisos para ese modelo concreto. 429 significa que estás sujeto a un límite de velocidad. Ninguno de estos tres debe tratarse como un problema de clave no válida.

Ejemplo mínimo de verificación

Ejecuta el siguiente comando directamente (sustituyéndolo por tu clave real) para confirmar si la clave en sí tiene algún problema:

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

Una clave válida devuelve inmediatamente un ID de tarea:

{"code": 200, "data": {"taskId": "tk-hiapi-..."}, "message": "success"}

Una clave incorrecta devuelve el 401 mostrado arriba. Si curl devuelve una respuesta con taskId pero tu aplicación sigue lanzando el error «invalid key», entonces el problema está en el código de tu aplicación que construye la solicitud, no en la clave.

Contenido relacionado

• Authentication docs: formato completo de las cabeceras, guía de rotación de claves y referencia de códigos de estado.
• Dashboard → API Keys: dónde crear, copiar y revocar claves.
• Rate limits: diferencias entre 429 y 401 y cuándo se activan.
• Quickstart: si es la primera vez que configuras hiapi, aquí tienes un recorrido completo por tu primera solicitud.

Preguntas frecuentes

¿«invalid API key» y estar sujeto a un límite de velocidad son lo mismo? No. Un 401 permission_denied significa que la clave en sí no ha sido aceptada. Un 429 con error_code: "RATE_LIMITED" significa que la clave es correcta pero las solicitudes llegan demasiado rápido; consulta los umbrales en la documentación de límites de velocidad.

Acabo de crear una clave nueva, pero sigue siendo inválida. ¿Por qué? Asegúrate de que la clave nueva se ha copiado realmente donde se origina la solicitud. Una clave nueva en el panel no corrige automáticamente un valor antiguo codificado, una variable de entorno sin definir o un archivo de configuración sin redesplegar.

¿hiapi exige la palabra literal «Bearer» en la cabecera? El formato documentado y compatible es Authorization: Bearer YOUR_API_KEY: úsalo siempre. No confíes en ningún comportamiento tolerante que hayas podido observar en tus pruebas; lo que no está documentado puede cambiar sin aviso.

¿Por qué funciona curl y mi aplicación no? Si curl con la misma clave funciona, la clave es válida y el problema está en cómo ensambla la solicitud tu aplicación: normalmente falta el prefijo Bearer en el código, se lee la variable de entorno antes de cargar .env o se pasa la clave a un parámetro equivocado en la librería de envoltura.

¿Qué significa error.type: "hiapi_error"? Es el sobre de error genérico de hiapi, que se usa tanto para este fallo de autenticación como para otros errores de solicitud. Consulta error.code (aquí permission_denied) para conocer el error real, no solo el tipo de sobre.