¿Por qué HiAPI cobra aunque una solicitud falle?

Síntoma

Envías una tarea de generación con POST a https://api.hiapi.ai/v1/tasks y luego consultas con GET /v1/tasks/:id; el resultado es "status": "fail", junto con un objeto error, por ejemplo {"code": "TASK_FAILED", "message": "task failed"}. El código de estado HTTP de esa consulta en sí es un 200 normal: HiAPI incluye la información de fallo en el cuerpo JSON, no en el código de estado. Como la tarea efectivamente pasó por queued → handling antes de fallar, es fácil pensar que este intento se cobró igual que una llamada normal. En realidad, que la tarea llegue al estado terminal fail no equivale a que se haya cobrado; pero si consultaste el saldo antes de que llegara el reembolso, la retención previa del momento de la creación sí hará que la cuenta parezca haber sido cobrada.

Causas habituales

1. Confundir la "retención previa" con un "cobro". HiAPI retiene el coste estimado de la tarea en el momento en que se crea, antes de que realmente empiece a ejecutarse. Esa retención se refleja de inmediato en tu saldo, pero todavía no es un cobro.
2. Consultar el saldo mientras la tarea está en curso. Entre queued/handling y el estado terminal, esa retención está "pendiente" por diseño. Solo el estado terminal (success o fail) la liquida.
3. Confundir "el downstream realmente se ejecutó pero falló" con "fue rechazado en la fase de creación". Una tarea que llega a status: "fail" (por ejemplo, error.code: "TASK_FAILED") sí se creó, sí se ejecutó y el downstream falló; la documentación de HiAPI indica claramente que, tras alcanzar este estado terminal, el importe retenido se devuelve automáticamente en su totalidad. En cambio, una solicitud que nunca obtuvo un taskId —por ejemplo, un 402 INSUFFICIENT_QUOTA devuelto de forma síncrona— fue rechazada antes de que existiera la tarea, así que no hubo nada que retener. Visto desde fuera, ambas son "fallos", pero solo la primera tocó realmente el mecanismo de retención.
4. Uso incorrecto de Idempotency-Key. Reenviar con la misma key y el mismo cuerpo de solicitud solo devuelve el taskId original; no crea ni cobra por segunda vez. Pero reenviar con la misma key y un cuerpo de solicitud distinto devuelve directamente 422 IDEMPOTENCY_KEY_MISMATCH en la fase de creación; y volver a llamar con la misma key mientras la primera llamada aún no ha terminado devuelve 409 IDEMPOTENCY_KEY_PROCESSING. Ninguna de estas dos rutas crea una tarea facturable.

Pasos de corrección

1. Consulta GET /v1/tasks/:id y revisa directamente data.status; no adivines el resultado de la facturación basándote solo en una captura del saldo en un momento dado. queued, handling y archiving son estados no terminales; solo success y fail son terminales.
2. Si data.status es "fail", es un resultado que se reembolsará. Revisa data.error.code (por ejemplo, TASK_FAILED) para conocer la causa y vuelve a consultar el saldo: el reembolso llega automáticamente después de que la tarea alcance este estado terminal.
3. Si la propia llamada POST /v1/tasks devolvió un código de estado no 2xx (400/402/409/415/422) y el cuerpo no contiene taskId, entonces no hay tarea que reembolsar, porque no se creó ninguna tarea ni se cobró nada. El caso concreto de saldo insuficiente se manifiesta como error_code: "INSUFFICIENT_QUOTA" en una respuesta 402.
4. Ve al panel de facturación de HiAPI y verifica el par de transacciones "retención—reembolso", en lugar de mirar solo la cifra de saldo en un momento determinado.
5. Al reintentar una tarea fallida, asigna una nueva Idempotency-Key a este nuevo intento real. No reenvíes con la key antigua y un cuerpo de solicitud distinto (provocará 422), ni vuelvas a enviar con la misma key mientras la primera solicitud sigue en proceso (provocará 409).
6. Si confirmas que la tarea ya alcanzó el estado terminal fail pero, pasado un tiempo, el importe retenido sigue sin devolverse, esto ya queda fuera del alcance de este mecanismo de reembolso automático: contacta directamente con soporte y no asumas que se recuperará por sí solo.

Ejemplo mínimo de verificación

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": { "prompt": "a minimalist desk setup, studio lighting" }
  }'

Aquí el campo model lleva el sufijo de ruta /text-to-image. En el momento de redactar este artículo, en el índice de modelos de HiAPI el grupo gpt-image-2 solo incluye entradas con sufijo de ruta (/text-to-image, /image-to-image), sin entradas con id sin sufijo. Si debes usar sufijo y cuál, guíate siempre por las entradas con availability: "online" de este índice de modelos en tiempo real; no copies la forma de otros modelos ni de documentación antigua.

Cuando obtengas el taskId devuelto, consulta:

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Una tarea fallida reembolsada tiene este aspecto:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "gpt-image-2/text-to-image",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_FAILED", "message": "task failed" }
  }
}

Enlaces internos relacionados

• Panel de facturación de HiAPI
• API unificada de tareas asíncronas de HiAPI: códigos de error y descripción de estados
• Tareas de HiAPI bloqueadas o con timeout: guía de diagnóstico y reintento
• Guía para corregir los errores "model not found" / "model not available" de HiAPI

FAQ

Si falla una tarea de imagen o vídeo, ¿HiAPI me cobra? No. En cuanto la tarea alcanza el estado terminal fail, el importe retenido en la creación se devuelve automáticamente en su totalidad.

Después de enviar la tarea, el saldo bajó de inmediato; la tarea falló más tarde, ¿por qué no ha vuelto el saldo? Esa reducción es la retención previa de la creación, no un cobro. Se liquida automáticamente cuando la tarea alcanza el estado terminal: con fail se devuelve, y solo con success se consume realmente.

¿Cuál es la diferencia entre un error 402 y el fallo de una tarea? 402 INSUFFICIENT_QUOTA significa que la tarea no llegó a crearse, así que no hay nada que retener ni nada que devolver. En cambio, una tarea que obtuvo un taskId y cuyo status pasó después a "fail" sí se creó, sí se ejecutó y luego falló el downstream; HiAPI devuelve automáticamente esa retención.

Si reintento con el mismo Idempotency-Key, ¿me cobran dos veces? No. Reenviar con la misma key y el mismo cuerpo de solicitud solo devuelve el taskId original y no crea una nueva tarea. Si con la misma key se cambia el cuerpo de solicitud, se devuelve directamente 422 IDEMPOTENCY_KEY_MISMATCH y tampoco se crea una tarea duplicada.

¿Dónde puedo ver los registros de retenciones y reembolsos? En la facturación y los registros de transacciones del panel de facturación de HiAPI.