Timeout dei task HiAPI ed errore 504: guida alla diagnosi e alla risoluzione

Nei task HiAPI, nella risposta restituita da GET /v1/tasks/{id} a volte può comparire "status": "fail", "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} — nota che il codice di stato HTTP di questa risposta è 200: questo è un reale stato di fallimento documentato da HiAPI, ovvero il task ha iniziato l'esecuzione ma non è riuscito a completarla entro il budget di tempo interno. Se invece quello che vedi non è questo JSON, ma il client genera direttamente un 504 Gateway Timeout HTTP grezzo, allora non è affatto una risposta dell'API di HiAPI: 504 non è presente in nessun elenco di codici di stato documentati da HiAPI. Questo articolo tratta separatamente i due casi: come interpretare e correggere un vero TASK_TIMEOUT; e da dove salta fuori il 504.

Che aspetto ha esattamente l'errore

Il flusso dei task HiAPI è asincrono: POST /v1/tasks restituisce immediatamente un taskId, dopodiché si effettua il polling su GET /v1/tasks/{id} per ottenere il risultato. Solo quando status raggiunge uno stato terminale compare il campo error. Un vero timeout si presenta così:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

Nota che il codice di stato HTTP di questa risposta è 200: la richiesta di polling in sé è riuscita, ciò che è fallito è il task, e i dettagli del fallimento sono in data.error. Questo è diverso da un fallimento sincrono in fase di creazione (ad esempio saldo insufficiente è 402, corpo della richiesta errato è 400): quel tipo di errore viene restituito subito sulla chiamata iniziale POST /v1/tasks, quando il task non è ancora stato creato. TASK_TIMEOUT può verificarsi solo su un task già creato con successo.

Invece 504, nella maggior parte dei casi, non è affatto un corpo di risposta: è un codice di stato che proxy, load balancer o alcune librerie client HTTP emettono da soli quando rinunciano ad attendere qualsiasi risposta. I codici di stato HTTP documentati da HiAPI sono 200, 400, 402, 404, 409, 415, 422, 503 — tra questi non c'è 504. Se quello che vedi è in realtà 401, si tratta di un altro problema (API Key non valida o disabilitata, non un timeout), fuori dall'ambito di questo articolo.

Cause comuni (ordinate per probabilità)

1. Un vero timeout a livello di task. Il modello ha ricevuto il task, ma non è riuscito a completarlo entro il budget di tempo interno. È esattamente lo scenario TASK_TIMEOUT mostrato sopra, più frequente su task più pesanti — durate video più lunghe, risoluzioni più alte, oppure un sovraccarico temporaneo del modello stesso.
2. Il 504 proviene dall'esterno di HiAPI. La stragrande maggioranza delle segnalazioni di "504" è in realtà il read timeout del client stesso (la libreria HTTP rinuncia perché non riesce ad attendere), oppure un proxy aziendale, VPN o load balancer tra te e api.hiapi.ai che interrompe la connessione secondo le proprie impostazioni di timeout. Dato che HiAPI non restituisce mai 504, si tratta di un problema di configurazione lato client o rete, non di un guasto di HiAPI.
3. Il task è ancora in esecuzione, ma viene erroneamente interpretato come timeout. queued, handling, archiving sono tutti stati non terminali: in questo momento il campo error non esiste affatto. Vedere una volta durante il polling uno stato diverso da success non equivale a un timeout.

Passi di risoluzione

1. Recupera il task tramite taskId e leggi direttamente status e error.code. Non indovinare la causa da un messaggio di eccezione generico nel codice client — chiama GET /v1/tasks/{id} e guarda il corpo della risposta stesso.
2. Se status è "fail" e error.code è "TASK_TIMEOUT": riprova. La modalità di risoluzione documentata è semplicemente questa — reinvia tramite una nuova chiamata POST /v1/tasks (ottenendo un nuovo taskId), senza bisogno di cambiare account o chiave.
3. Se il task in sé è particolarmente pesante, controlla prima gli input. Durate video più lunghe, risoluzioni più alte o prompt molto grandi/complessi avvicinano il modello al limite del suo budget di tempo. Se la stessa configurazione va ripetutamente in timeout, prova una risoluzione/durata inferiore, oppure cambia modello.
4. Se quello che vedi è in realtà un 504 grezzo (senza un corpo di risposta JSON con error.code), il problema è fuori da HiAPI. Controlla il read timeout configurato nel tuo client o SDK HTTP — molti valori predefiniti sono troppo brevi (10-30 secondi), e in un flusso asincrono non si dovrebbe mai bloccare una richiesta lunga, ma fare polling separatamente. Verifica anche se stai passando attraverso un proxy aziendale, un gateway VPN o un load balancer, che potrebbero interrompere la connessione secondo le proprie impostazioni di timeout, del tutto indipendentemente da HiAPI.
5. Se status è ancora queued, handling o archiving, non riprovare ancora. Nulla è realmente fallito. Per una diagnosi più completa puoi consultare la guida alla diagnosi di task HiAPI bloccati/timeout (in inglese).

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" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

Questo restituisce immediatamente un taskId:

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

Poi esegui il polling:

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

Un task normale alla fine restituirà "status": "success" con il risultato dell'output. Un task realmente andato in timeout restituirà la struttura TASK_TIMEOUT mostrata sopra. Se invece ottieni un 504 a livello di connessione, senza alcun corpo di risposta JSON, allora significa che la risposta non è proprio riuscita a tornare dall'API di HiAPI — controlla le impostazioni di timeout del tuo client e il percorso di rete seguendo i passi sopra, invece di sospettare problemi all'account.

Link interni correlati

• Console HiAPI
• Creare un task asincrono (documentazione API)
• Guida alla diagnosi di task HiAPI bloccati/timeout (in inglese)

FAQ

Il TASK_TIMEOUT di HiAPI e l'HTTP 504 Gateway Timeout sono la stessa cosa? No. TASK_TIMEOUT è un codice di errore documentato da HiAPI, che compare in una normale risposta 200 e rappresenta il fatto che il status del task stesso è diventato fail, ovvero il task è andato in timeout internamente. 504 è un codice di stato HTTP generico restituito da alcuni proxy, load balancer o librerie client HTTP quando rinunciano ad attendere la risposta; l'API di HiAPI non documenta né restituisce mai 504, quindi il 504 letterale che vedi proviene necessariamente da un anello tra te e HiAPI, o dal tuo stesso client, che ha rinunciato ad attendere, non da un guasto del server HiAPI.

Cosa devo fare quando incontro TASK_TIMEOUT? Basta reinviare un nuovo task. La modalità di risoluzione documentata per TASK_TIMEOUT è semplicemente riprovare; non esiste un passo di sblocco separato, e se non si verifica ripetutamente un timeout con gli stessi input, non è necessario modificare prompt o parametri.

Riprovare un task andato in timeout comporta due addebiti? La tabella dei codici di errore documentati da HiAPI non lo specifica esplicitamente. Se questo è importante per te, verifica nella console i record di utilizzo usando questo specifico taskId, senza basarti su supposizioni.

Il mio client HTTP ha generato un'eccezione di timeout, non un TASK_TIMEOUT in formato JSON: è la stessa cosa? No. Un timeout del client stesso (ad esempio ReadTimeout della libreria HTTP, o un 504 restituito da un proxy aziendale) significa che la tua connessione ha rinunciato prima di ricevere qualsiasi risposta da HiAPI, e questo non implica che il task stesso sia fallito. Dato che /v1/tasks è asincrono, la soluzione comune è aumentare il read timeout del client (o addirittura non bloccarsi in attesa sulla POST iniziale) ed eseguire separatamente il polling su GET /v1/tasks/{id} fino a vedere uno stato terminale.

Il task è in stato queued o handling da diversi minuti, senza errori: è un timeout? Non ancora. queued, handling, archiving sono tutti stati non terminali; il campo error compare solo quando status diventa fail. Se il task davvero non si stabilizza mai, puoi consultare nella guida alla diagnosi di task HiAPI bloccati/timeout (in inglese) l'analisi completa delle cause in corso, come l'accumulo in coda.