Errori upstream HiAPI 502 / 503: cause e come risolverli

Chiami POST https://api.hiapi.ai/v1/tasks (oppure esegui il polling di GET /v1/tasks/{id}) e invece del solito 200 con taskId ricevi 502 Bad Gateway o 503 Service Unavailable. Entrambi sono risposte 5xx: il problema è lato server o trasporto, non la tua richiesta. Non hai inviato parametri errati, una chiave errata o un payload malformato. Il 503 è il segnale di "piattaforma temporaneamente non disponibile" documentato nella documentazione di HiAPI, che ti dice di riprovare; il 502 è invece una risposta a livello di gateway generata da qualche punto della catena. Questa guida spiega come confermarlo, come riprovare in modo sicuro senza duplicare il lavoro e come distinguere 502/503 dai timeout 504 e dai risultati TASK_FAILED.

Che aspetto hanno concretamente 502 o 503

Sulla riga di stato HTTP vedrai uno dei seguenti, invece del normale 200:

• 503 Service Unavailable —— questo è documentato. La documentazione dell'API asincrona di HiAPI elenca 503 come "piattaforma temporaneamente non disponibile; riprova più tardi con backoff esponenziale", con il codice di business corrispondente TEMPORARILY_UNAVAILABLE ("Servizio di generazione temporaneamente non disponibile. Riprova più tardi; se il problema persiste, contatta il supporto."). Gli errori sincroni di HiAPI usano una busta JSON piatta — la documentazione indica per il 400: {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} — quindi anche un 503 restituito dall'API dovrebbe usare la stessa busta, con error_code: "TEMPORARILY_UNAVAILABLE".
• 502 Bad Gateway —— questo non è tra i codici di stato documentati da HiAPI. In HTTP standard, 502 indica che un gateway o proxy ha ricevuto una risposta non valida o vuota dal hop successivo che ha tentato di contattare. Il 502 che ricevi è quindi prodotto da un gateway della catena — potrebbe essere il livello edge/CDN, un load balancer o un proxy della tua rete — e non dall'applicazione HiAPI che restituisce la sua solita busta JSON. Il corpo della risposta è di solito una breve pagina HTML o di testo semplice del gateway, e proprio questo corpo non-JSON è un segnale: si tratta di una condizione di trasporto/gateway, non di un errore applicativo con un payload fisso e documentato.

In entrambi i casi lo stato è 5xx: il problema è lato server o trasporto, non la tua richiesta. È l'opposto di 4xx — 400 (parametri errati), 401 (chiave errata; HiAPI restituisce {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}} annidato) o 402 (saldo insufficiente) — che richiedono di modificare qualcosa dalla tua parte per essere risolti. I 502/503 non si risolvono modificando il payload.

Cause comuni (in ordine di probabilità decrescente)

1. Breve sovraccarico o finestra di manutenzione della piattaforma → 503 TEMPORARILY_UNAVAILABLE. È una situazione prevista e documentata. Si risolve da sola; il backoff con nuovo tentativo avrà successo.
2. Fluttuazione momentanea di un gateway o proxy della catena → 502. Il livello edge/CDN, il load balancer o un proxy della tua rete non è riuscito temporaneamente a inoltrare la risposta. Anche in questo caso è temporaneo.
3. Un picco di traffico ha attivato una limitazione. In caso di carico elevato potresti invece vedere 429 RATE_LIMITED ("Riprova più tardi; evita di reinviare immediatamente la stessa richiesta"). Se lo stato è 429, la soluzione è ridurre la velocità di invio, non riprovare con più forza.
4. Il backend del modello richiesto è temporaneamente non disponibile. HiAPI lo registra a livello di task come MODEL_UNAVAILABLE ("Riprova più tardi o cambia modello"); un guasto temporaneo a livello di piattaforma che serve quel modello può anche manifestarsi come 503.
5. Non è un errore di chiave, un corpo della richiesta malformato o un saldo insufficiente. Questi sono rispettivamente 401 / 400 / 402 e non si manifestano come 502 o 503.

Come risolvere, in ordine

1. Verifica che sia 5xx e non 4xx. Controlla prima il codice di stato. 502/503 sono lato server/trasporto; 400, 401, 402, 404, 409, 415, 422 e 429 sono dalla tua parte. Se è davvero 502/503, non iniziare a riscrivere il corpo della richiesta — questo aiuta solo con i 4xx.
2. Riprova con backoff esponenziale e jitter. La documentazione richiede esplicitamente il backoff esponenziale per il 503. Un pattern client sicuro è partire da circa 1 secondo, raddoppiare a ogni tentativo (2 s, 4 s, 8 s…) con un limite di circa 30–60 secondi, aggiungendo jitter casuale per evitare che molti client riprovino in sincrono. Questi intervalli sono pattern client consigliati, non garanzie temporali pubblicate da HiAPI.
3. Rendi l'invio idempotente. Imposta l'header Idempotency-Key su POST /v1/tasks (qualsiasi stringa UTF-8, fino a 255 byte). Se un 502/503 ti lascia in dubbio se il task sia stato effettivamente creato, riprovare con la stessa chiave è sicuro: stessa chiave + stesso corpo della richiesta restituiscono il taskId originale con l'header di risposta Idempotent-Replay: true, senza creare un secondo task né addebitare una seconda volta. Le chiavi sono limitate all'account e scadono dopo 24 ore. La convenzione completa è nella documentazione Unified Async API.
4. Non reinviare alla cieca una POST senza chiave. Se hai inviato senza Idempotency-Key e hai ricevuto un 502/503, potresti aver già creato un task che non vedi — non hai un taskId su cui fare polling, quindi un nuovo tentativo ingenuo rischia lavoro duplicato e addebiti duplicati. Aggiungi la chiave prima di qualsiasi retry su larga scala.
5. Se il 502/503 avviene durante il polling, continua a fare polling. Un 5xx restituito da GET /v1/tasks/{id} non cambia lo stato del task. Gli stati terminali (success / fail) una volta raggiunti sono fissi e non si trasformano mai l'uno nell'altro, quindi basta riprovare il polling dopo il backoff. In alternativa, registra callback.url per ricevere una notifica allo stato terminale senza dover fare polling attraverso 5xx temporanei — la consegna è at-least-once, quindi deduplica per taskId.
6. Distinguilo dai fallimenti a livello di task. Se invece ricevi HTTP 200 con "status": "fail", non è un 502/503 — il task è stato accettato, eseguito e fallito. Gestisci TASK_FAILED ("Riprova una volta; se il problema persiste, contatta il supporto") o TASK_TIMEOUT ("Riprova il task") secondo le rispettive indicazioni, non con un retry di gateway alla cieca.
7. Se persiste, scala il problema invece di insistere. Se il 502/503 continua a comparire dopo diversi tentativi con backoff nell'arco di alcuni minuti, trattalo come un evento temporaneo della piattaforma, non come un problema da risolvere con la forza. Smetti di riprovare in modo aggressivo e contatta il supporto allegando il request_id se presente nel corpo dell'errore. Puoi verificare dal HiAPI Console che il tuo account e la connettività siano a posto.

Confronto tra 502 / 503, 504 e TASK_FAILED

È facile confonderli, perché tutti significano "non è tornato qualcosa di pulito", ma richiedono gestioni diverse:

Risposta	Codice di stato HTTP	Origine	Il task è stato addebitato?	Cosa fare
503 Service Unavailable	503 (documentato)	Piattaforma HiAPI — temporaneamente non disponibile o sovraccarica	Non determinabile dalla risposta; il task potrebbe esistere già	Riprova con backoff e la stessa Idempotency-Key
502 Bad Gateway	502 (non nella documentazione HiAPI)	Gateway/proxy della catena (edge, load balancer o il tuo proxy)	Non determinabile dalla risposta	Riprova in modo idempotente con backoff; se compare solo dalla tua rete, sospetta un proxy dalla tua parte
504 Gateway Timeout	504 (non nella documentazione HiAPI)	Gateway o proxy della catena che ha smesso di attendere (la documentazione HiAPI non elenca il 504)	Non determinabile dalla risposta	Come per il 502; HiAPI riporta i propri timeout come TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI — il task è stato eseguito ma ha superato il budget di tempo	No (l'importo riservato è stato rimborsato)	Riprova il task come nuova richiesta
TASK_FAILED	200 + "status": "fail"	HiAPI — il task è stato accettato ed eseguito, poi è fallito	No (l'importo riservato è stato rimborsato)	Riprova una volta, poi leggi error.message
429 RATE_LIMITED	429	HiAPI — stai inviando troppo velocemente	Nessun task	Backoff; non reinviare immediatamente
400 / 401 / 402	4xx	HiAPI — lato client (errore di corpo/chiave/saldo)	No	Correggi richiesta, chiave o saldo; riprovare non serve

Regola pratica: 502/503/504 sono errori di trasporto HTTP e non contengono alcun risultato di task; mentre TASK_FAILED / TASK_TIMEOUT arrivano come HTTP 200 con "status": "fail" e un oggetto error. I primi significano "non sai se la richiesta è arrivata"; i secondi "la richiesta è arrivata, il task è stato eseguito ed è fallito".

Esempio minimo di verifica

Usa un invio pulito per dimostrare che chiave e connettività funzionano, e isola il 502/503 come problema temporaneo. Usa un model id che sai essere disponibile (ad esempio gpt-image-2/text-to-image) e includi Idempotency-Key, così i retry sono sicuri:

# Un invio sano restituisce 200 con un taskId. Se questo funziona ma una
# chiamata specifica ha appena restituito 502/503, quel 502/503 era temporaneo — non la tua configurazione.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"una bicicletta rossa su sfondo bianco"}}'

# Poi fai polling del task appena creato (sostituisci con l'id restituito):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Se l'invio stesso restituisce 200 e un taskId, la tua autenticazione e il percorso di rete sono a posto, e il precedente 502/503 era una condizione temporanea di server/trasporto — riprova la chiamata fallita (riutilizzando la stessa Idempotency-Key restituirai il task originale, non un duplicato). Se invece l'invio restituisce 401 o 400, è un problema lato client, non un 502/503.

Letture correlate

• Timeout dei task HiAPI e errore 504: come risolvere —— perché un 504 grezzo non proviene da HiAPI e cosa significa TASK_TIMEOUT.
• Errore HiAPI TASK_FAILED: cause e come risolverlo —— gestire i task che restituiscono 200 + "status": "fail".
• Quando i job di hiapi /v1/tasks si bloccano o vanno in timeout: diagnosi e retry —— approfondimento su intervalli di polling e strategie di retry.
• Come risolvere l'errore di rate limit (429) di HiAPI —— quando il vero problema è la velocità di invio e non la disponibilità.
• Perché le richieste HiAPI fallite vengono comunque addebitate? —— come funzionano riserve e rimborsi per i task falliti.

Domande frequenti

Il 502 o 503 è colpa mia? No. Entrambi sono risposte 5xx, lato server o trasporto. La tua API key e il corpo della richiesta non sono la causa — i 4xx (400/401/402) sono la categoria causata da te e che puoi correggere. La risposta corretta a un 502/503 è un retry idempotente, non modificare il codice.

Qual è la differenza tra 502 e 503 su HiAPI? Il 503 è il codice "piattaforma temporaneamente non disponibile" documentato da HiAPI (error_code: TEMPORARILY_UNAVAILABLE) e proviene dalla piattaforma stessa. Il 502 non è tra i codici di stato documentati da HiAPI; in HTTP standard viene emesso da un gateway o proxy della catena quando l'upstream restituisce una risposta non valida. Entrambi sono temporanei e richiedono un retry con backoff, ma il 502 può anche indicare un proxy della tua rete.

In cosa differisce il 503 dal 504? 503 significa che il servizio è temporaneamente non disponibile o sovraccarico. 504 Gateway Timeout significa che da qualche parte si è atteso troppo a lungo una risposta. La documentazione HiAPI non elenca il 504; se lo vedi, un gateway o proxy della catena ha rinunciato ad attendere. Lo stato "durata eccessiva" proprio di HiAPI è il risultato di task TASK_TIMEOUT (HTTP 200 + "status": "fail"). Vedi la guida sul 504 sopra.

Come distinguere 502/503 dal risultato TASK_FAILED? Guarda il codice di stato HTTP. 502/503 sono errori HTTP senza payload di task. TASK_FAILED arriva come HTTP 200 con "status": "fail" e un oggetto error — il task è stato accettato ed eseguito. Usa il retry con backoff per i 502/503; per TASK_FAILED riprova una volta, poi leggi error.message.

Se riprovo dopo aver ricevuto un 502/503, mi verrà addebitato due volte o verrà creato un task duplicato? Se invii l'header Idempotency-Key su POST /v1/tasks, no. Riusare la stessa chiave + corpo della richiesta restituisce il taskId originale (Idempotent-Replay: true) senza creare un task duplicato. Inoltre i task falliti non vengono mai addebitati — non appena un task raggiunge lo stato terminale di fallimento, l'importo riservato alla creazione viene rimborsato per intero.

Per quanto tempo devo fare backoff e quando devo scalare il problema? Usa un backoff esponenziale con jitter (ad esempio 1 s, 2 s, 4 s, 8 s, con un limite e un elemento casuale). Se il 502/503 continua a tornare dopo diversi tentativi nell'arco di alcuni minuti, smetti di riprovare in modo aggressivo e contatta il supporto allegando il request_id presente nel corpo dell'errore — un 5xx persistente di solito indica un evento temporaneo della piattaforma, non qualcosa che un ciclo di retry più rapido possa risolvere.

Devo modificare il payload della richiesta quando vedo un 502/503? No. Il 502/503 non è un errore di validazione, quindi modificare i parametri non serve e potrebbe mascherare la vera causa temporanea. Mantieni la richiesta invariata, aggiungi la Idempotency-Key se non l'hai già fatto, e riprova con backoff.