HiAPI devuelve 403 sin permiso de modelo: guía de diagnóstico y solución

Al llamar al endpoint /v1/tasks de HiAPI, si recibes un HTTP 403, el cuerpo de la respuesta suele tener esta estructura: {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Esto indica que tu API Key es válida y que la autenticación ya se ha superado, pero que esta clave no está autorizada a llamar al modelo o endpoint que has solicitado; esto es un problema distinto del 401 de «clave inválida o ausente»: el 401 significa que ni siquiera se ha reconocido la identidad, mientras que el 403 significa que se ha reconocido, pero esta clave no puede usar el recurso actual. La solución de la mayoría de los 403 es muy directa: comprobar la correspondencia entre la clave y el modelo, y reintentar con una clave que tenga permisos.

Causas habituales

1. La API Key no está autorizada a usar el modelo solicitado: la definición oficial de 403 en la documentación es precisamente «la clave de API no tiene este permiso». Es el escenario más frecuente y suele darse cuando se usa la misma clave para llamar a modelos fuera de su ámbito de permisos.
2. Se ha usado la clave equivocada: por ejemplo, cuando debería usarse la clave principal, se usa por error una clave de otra cuenta o proyecto con un ámbito de permisos más reducido; al copiar y pegar también es fácil introducir espacios sobrantes o cortar la clave.
3. Confundir «clave inválida» (401) con «clave sin permiso» (403): en ambos mensajes de error pueden aparecer términos relacionados con «permiso», y diagnosticarlos con el mismo enfoque lleva a una dirección equivocada. El método concreto para distinguirlos se explica más abajo.

Pasos de solución

1. Confirma primero que realmente se devuelve un 403 y no un 401: fíjate en el código de estado HTTP en sí, no solo en el texto del mensaje de error, porque el código de error permission_denied puede aparecer tanto en 401 como en 403; lo que distingue es el código de estado, no el texto.
2. Ve a la gestión de claves de API y comprueba a quién pertenece esta clave: confirma que la clave usada realmente en la petición es la esperada, y no una clave de una cuenta de pruebas, de un proyecto antiguo o de otra persona.
3. Comprueba si el modelo actual está dentro del ámbito disponible para esta clave: puedes consultar la documentación de autenticación y los precios de HiAPI para confirmar que el modelo existe realmente y está dentro de tu ámbito de llamada; si el ID del modelo está mal escrito o ya no está disponible, el error debería ser otro código distinto de permission_denied, lo que puede ayudarte a distinguir el tipo de problema.
4. Cambia a una clave que confirmes que tiene permisos y reintenta una vez con exactamente el resto de parámetros iguales, para verificar si el problema desaparece al cambiar la clave.
5. Si tras comprobarlo la clave y el modelo son correctos y el 403 sigue reproduciéndose de forma estable, registra el request_id del cuerpo de la respuesta y contacta con soporte; no reintentes la misma petición repetidamente sin haber confirmado antes la causa.

Ejemplo mínimo de verificación

A continuación se muestra, con una petición que provoca un 403 y el reintento tras la solución, la estructura real de respuesta en ambos estados (sustituye MODEL_ID por el modelo que estás llamando realmente y del que sospechas que no tienes permiso):

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "a simple test prompt"
  }'

Respuesta cuando no hay permiso:

{
  "error": {
    "code": "permission_denied",
    "message": "La API Key actual no puede usar este modelo por ahora; comprueba los permisos o cambia de clave.",
    "request_id": "req_xxxxxxxx",
    "type": "hiapi_error"
  }
}

Tras cambiar a una clave con permisos y mantener el resto de parámetros igual, reintenta:

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

Puedes observar que las estructuras de ambos cuerpos de respuesta son distintas: los errores de la capa de autenticación/permisos, como el 403, se envuelven uniformemente en un objeto error; en cambio, los errores que se producen tras pasar la validación de permisos de la clave y entrar realmente en las reglas de negocio concretas (por ejemplo, un 402 por saldo insuficiente) tienen un cuerpo de respuesta con estructura plana de code / data / message. Según la estructura que veas, podrás determinar a grandes rasgos si el problema está en la capa de autenticación y permisos o en la de reglas de negocio concretas.

Enlaces internos relacionados

• Gestión de claves de API
• Documentación de autenticación
• Precios de HiAPI

FAQ

¿Cuál es la diferencia concreta entre 403 y 401? El 401 indica que la clave en sí no es válida o que la petición no incluye ninguna clave: no se ha superado ni siquiera el paso de autenticación de identidad. El 403 indica que la autenticación de identidad se ha superado (la clave es válida), pero esta clave no está autorizada a usar el modelo o recurso que has solicitado. La estructura del cuerpo de respuesta es la misma en ambos casos (un objeto envuelto en error.code); la clave para distinguirlos es el propio código de estado HTTP, no el texto del mensaje de error.

Si después de cambiar de clave sigue devolviendo 403, ¿significa que hay un problema con la cuenta? Primero confirma que la nueva clave pertenece realmente a la misma cuenta o proyecto con permisos y que al copiar y pegar no se han introducido espacios sobrantes, saltos de línea ni cortes. Si tras comprobarlo sigue reproduciéndose, contacta con soporte e incluye el request_id del cuerpo de la respuesta.

¿El 403 se debe a saldo insuficiente? No. El saldo insuficiente corresponde a otro código de error (INSUFFICIENT_QUOTA, HTTP 402) y es algo distinto de los permisos: el 403 solo indica «si esta clave tiene derecho a llamar a este modelo» y no tiene relación con el saldo de la cuenta.

Si en el mensaje de error aparece la palabra «permiso», ¿es necesariamente un 403? No necesariamente. El código de error permission_denied puede aparecer tanto en 401 como en 403; no se puede determinar solo por la palabra clave del texto, hay que fijarse directamente en el código de estado HTTP.