¿Qué hacer cuando HiAPI devuelve 402 por saldo insuficiente (INSUFFICIENT_QUOTA)? Causas y pasos para solucionarlo

Al llamar a la API de HiAPI, ocasionalmente se recibe una respuesta HTTP 402 y el campo error_code del cuerpo de la respuesta es INSUFFICIENT_QUOTA. Esto significa que el saldo de Credits de la cuenta se ha agotado; no tiene relación con si la API Key es válida, si el formato de la solicitud es correcto ni con haber alcanzado el límite de solicitudes. La tarea se rechaza antes de crearse, por lo que no se genera ningún cargo. La solución es casi siempre la misma: ir a la página de facturación para añadir Credits a la cuenta y volver a intentar exactamente la misma solicitud que falló.

Causas habituales

1. El saldo ya era 0. Las cuentas nuevas reciben Credits de bienvenida por registro; cuando tanto estos como las recargas posteriores se agotan, cualquier llamada para crear una tarea devuelve 402 hasta que el saldo vuelva a ser positivo.
2. Llamadas intensivas en poco tiempo: el saldo se consume más rápido de lo esperado. Los modelos de vídeo suelen facturar por segundos de salida; los Credits consumidos al ejecutar varios clips de vídeo seguidos suelen superar con creces los de la misma cantidad de tareas de imagen, lo que hace fácil no darse cuenta de que el saldo se ha agotado.
3. Confundir un 401 o un 429 con un 402. Revisa directamente el código de estado HTTP y el campo error_code: el 401 (error_code similar a permission_denied, la Key no es válida o está deshabilitada) y el 429 (error_code: RATE_LIMITED, solicitudes demasiado rápidas) parecen "fallos de llamada", pero su solución es totalmente distinta de la del 402; si se mezclan en los registros, es fácil buscar en la dirección equivocada.

Pasos para solucionarlo

1. Primero confirma el saldo. Abre la página de facturación de la consola y consulta el saldo actual de Credits; este paso confirma directamente si el 402 se debe realmente a un problema de saldo.
2. Recarga la cuenta. Añade Credits también desde la página de facturación; no hay ningún paso adicional de "desbloqueo": en cuanto el saldo sea positivo, la creación de tareas funcionará de inmediato.
3. Vuelve a intentar la misma solicitud. No hace falta cambiar ningún código ni parámetro. El mismo prompt, model y el resto de campos funcionarán directamente cuando haya saldo suficiente; si no sabes cuánto cuesta aproximadamente una llamada de un modelo concreto, puedes consultar primero la página de precios.
4. Configura alertas de saldo para no volver a encontrarte con esto. En los ajustes de la consola existe la función de alertas de saldo (Balance Alerts); cuando el saldo baje del umbral que establezcas, recibirás un aviso por correo, de modo que puedas recargar antes de quedarte realmente sin saldo.

Ejemplo mínimo de verificación

Con la siguiente solicitud mínima puedes confirmar de forma independiente que el problema está en el saldo de la cuenta y descartar interferencias del modelo o del propio SDK:

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

Con el saldo a cero, la respuesta tiene la siguiente estructura:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

Después de recargar, si vuelves a intentarlo con la misma solicitud, obtendrás una respuesta normal de creación de tarea:

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

Ten en cuenta que el campo code coincide con el código de estado HTTP, error_code es el valor estable que se usa para ramificar la lógica y data siempre es null cuando falla la creación.

Enlaces internos relacionados

• Precios de HiAPI
• Gestión de facturación y saldo
• Crear tareas asíncronas (documentación de la API)

FAQ

¿Cómo es posible que el saldo se agote de repente sin ningún aviso previo? Por defecto, solo se descubre que el saldo es insuficiente cuando una tarea falla realmente con un 402. Activa las alertas de saldo (Balance Alerts) en los ajustes de la consola: cuando el saldo baje del umbral que establezcas, recibirás un correo y podrás recargar con antelación.

¿Puede un 402 interrumpir una tarea que ya está en ejecución? No. INSUFFICIENT_QUOTA se devuelve en la fase de creación de la tarea; en ese momento la tarea aún no existe, así que no tiene sentido hablar de interrumpir una tarea en ejecución: solo bloquea la creación de nuevas tareas.

¿Se cobra por las solicitudes que fallan con 402? No. La comprobación de saldo ocurre antes de que la tarea se cree realmente; un 402 significa que la tarea no se ha creado y que no se ha descontado ningún Credit de la cuenta.

¿Es lo mismo un 402 que un límite de solicitudes (429)? No. El límite de solicitudes devuelve 429 con error_code RATE_LIMITED, lo que significa que las solicitudes se envían demasiado rápido; el 402 significa que el saldo de Credits de la cuenta es insuficiente y no tiene relación con la frecuencia de las solicitudes, y su solución también es distinta.

¿Cómo saberlo antes de que se agote el saldo? Abre la página de facturación de la consola, donde puedes consultar el saldo actual de Credits y el historial completo de consumo, y también configurar allí el umbral de las alertas de saldo.