Perché HiAPI addebita comunque quando una richiesta fallisce?

Sintomo del problema

Hai inviato un task di generazione con POST a https://api.hiapi.ai/v1/tasks, poi hai fatto polling con GET /v1/tasks/:id e hai ottenuto "status": "fail", più un oggetto error, ad esempio {"code": "TASK_FAILED", "message": "task failed"}. Il codice di stato HTTP di questa chiamata di polling è un normale 200 — HiAPI incapsula le informazioni di errore nel body JSON, non nel codice di stato. Poiché il task è effettivamente passato per queued → handling prima di fallire, è facile pensare che questo tentativo sia stato addebitato come una chiamata normale. In realtà, il fatto che il task raggiunga lo stato terminale fail non equivale a un addebito — ma se hai controllato il saldo prima che il rimborso fosse accreditato, la prenotazione effettuata alla creazione fa effettivamente sembrare che il denaro sia stato addebitato.

Cause comuni

1. Confondere la "prenotazione" con l'"addebito". HiAPI prenota il costo stimato del task nel momento stesso in cui il task viene creato, prima che inizi davvero l'esecuzione. Questa prenotazione si riflette immediatamente nel tuo saldo — ma non è ancora un addebito.
2. Controllare il saldo mentre il task è in corso. Tra queued/handling e lo stato terminale, questa prenotazione resta volutamente "in sospeso": è un comportamento previsto. Solo lo stato terminale (success o fail) la liquida.
3. Confondere "il downstream è davvero partito ma è fallito" con "la richiesta è stata rifiutata già in fase di creazione". Un task che arriva a status: "fail" (ad esempio con error.code: "TASK_FAILED") è stato davvero creato, è stato davvero eseguito e il downstream è fallito — la documentazione di HiAPI specifica chiaramente che, una volta che il task raggiunge questo stato terminale, l'importo prenotato viene restituito automaticamente per intero. Invece una richiesta che non ha mai ottenuto un taskId — ad esempio un 402 INSUFFICIENT_QUOTA restituito in modo sincrono — è stata rifiutata prima che il task esistesse, quindi non c'è stato nulla da prenotare. Dall'esterno entrambi i casi sembrano "falliti", ma solo il primo ha davvero toccato il meccanismo di prenotazione.
4. Uso errato di Idempotency-Key. Ripetere la stessa richiesta con la stessa key e lo stesso body restituisce solo il taskId originale, senza creare nulla né addebitare una seconda volta. Ma ripetere con la stessa key e un body diverso restituisce direttamente in fase di creazione 422 IDEMPOTENCY_KEY_MISMATCH; ripetere con la stessa key mentre la prima chiamata non è ancora stata elaborata restituisce 409 IDEMPOTENCY_KEY_PROCESSING. Nessuno di questi due percorsi crea un task fatturabile.

Passaggi di risoluzione

1. Fai polling su GET /v1/tasks/:id e controlla direttamente data.status — non indovinare l'esito della fatturazione basandoti solo su uno screenshot del saldo in un dato momento. queued, handling e archiving sono tutti stati non terminali; solo success e fail sono terminali.
2. Se data.status è "fail", questo è un esito che verrà rimborsato. Controlla data.error.code (ad esempio TASK_FAILED) per capire la causa, poi ricontrolla il saldo — il rimborso viene accreditato automaticamente dopo che il task raggiunge questo stato terminale.
3. Se la chiamata POST /v1/tasks stessa ha restituito un codice di stato non 2xx (400/402/409/415/422) e il body non contiene taskId, non c'è alcun task da rimborsare — perché nessun task è stato creato né addebitato. Il caso specifico di saldo insufficiente si manifesta come error_code: "INSUFFICIENT_QUOTA" nella risposta 402.
4. Controlla nel pannello di fatturazione HiAPI la coppia di transazioni "prenotazione—rimborso", invece di guardare solo il numero del saldo in un dato momento.
5. Quando ritenti un task fallito, assegna a questo nuovo tentativo effettivo una nuova Idempotency-Key. Non ripetere con la vecchia key e un body diverso (attiverebbe 422) e non inviare di nuovo con la stessa key mentre la prima richiesta è ancora in elaborazione (attiverebbe 409).
6. Se sei certo che il task ha raggiunto lo stato terminale fail ma dopo un po' di tempo l'importo prenotato non è ancora stato restituito, questo va oltre l'ambito di questo meccanismo di rimborso automatico — contatta direttamente il supporto, non dare per scontato che si risolva da solo.

Esempio minimo di verifica

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" }
  }'

Qui il campo model include il suffisso di routing /text-to-image. Al momento della stesura di questo articolo, nell'indice dei modelli HiAPI il gruppo gpt-image-2 contiene solo voci con suffisso di routing (/text-to-image, /image-to-image), senza voci con id nudo. Se serva il suffisso e quale suffisso usare, fai sempre riferimento alle voci con availability: "online" in questo indice dei modelli in tempo reale, senza copiare la sintassi di altri modelli o di documentazione obsoleta.

Dopo aver ottenuto il taskId restituito, fai polling:

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

Un task fallito e rimborsato appare così:

{
  "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" }
  }
}

Link interni correlati

• Pannello di fatturazione HiAPI
• API unificata per task asincroni HiAPI: codici di errore e descrizione degli stati
• Task HiAPI bloccati o in timeout: guida alla diagnosi e al retry
• Guida alla correzione degli errori HiAPI "model not found" / "model not available"

FAQ

Se un task di immagini o video fallisce, HiAPI mi addebita comunque? No. Una volta che il task raggiunge lo stato terminale fail, l'importo prenotato alla creazione viene restituito automaticamente per intero.

Dopo aver inviato il task il saldo è subito diminuito, e poi il task è fallito: perché il saldo non è tornato come prima? Quella riduzione è la prenotazione effettuata alla creazione, non un addebito. Viene liquidata automaticamente quando il task raggiunge lo stato terminale — con fail viene restituita, solo con success viene realmente consumata.

Qual è la differenza tra un errore 402 e un task fallito? 402 INSUFFICIENT_QUOTA significa che il task non è mai stato creato, quindi non c'è nulla da prenotare né da rimborsare. Invece un task che ha ottenuto un taskId e il cui status è poi diventato "fail" è stato davvero creato, è stato davvero eseguito e poi il downstream è fallito; HiAPI restituisce automaticamente questa prenotazione.

Se ritento con la stessa Idempotency-Key, vengo addebitato due volte? No. Ripetere con la stessa key e lo stesso body restituisce solo il taskId originale e non crea un nuovo task. Se con la stessa key si cambia il body, viene restituito direttamente 422 IDEMPOTENCY_KEY_MISMATCH e non viene creato alcun task duplicato.

Dove posso vedere i record di prenotazione e rimborso? Nella fatturazione e nei registri delle transazioni del pannello di fatturazione HiAPI.