Home → Assistenza

Timeout 524 sulle richieste API lunghe

Cosa vedi

• error code: 524
• A timeout occurred
• The request timed out after N seconds with no response body

Perché succede

Il dettaglio importante è che il cronometro misura il tempo fino al primo byte, non la durata totale. Una risposta in streaming inizia a emettere quasi subito, quindi può durare molti minuti senza mai toccare il limite. Una richiesta senza streaming con una lunga fase di ragionamento non invia nulla finché non ha finito del tutto, ed è proprio quella forma a essere tagliata.

Ecco perché il problema sembra casuale. Lo stesso prompt riesce quando finisce in fretta e fallisce quando il modello ragiona più a lungo, e la cosa dipende dalla profondità del ragionamento, non da qualcosa che hai cambiato.

Verifica se la causa è questa

Esegui la stessa richiesta con lo streaming attivo e disattivo. Se una sopravvive e l'altra no, l'hai trovato:

# non-streaming — vulnerable to the time-to-first-byte limit
curl -sS -X POST 'YOUR_BASE_URL/chat/completions' \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"MODEL","stream":false,"messages":[...]}'

# streaming — first byte arrives in well under a second
  -d '{"model":"MODEL","stream":true,"messages":[...]}'

Lo streaming ti dà anche un modo di fallire molto migliore: se qualcosa va storto a metà, conservi l'output parziale invece di perdere l'intera chiamata.

Come risolvere

1. Attiva lo streamingRisolve il problema alla radice per quasi tutti i carichi di lavoro, ed è una modifica di una riga. La maggior parte degli SDK e degli strumenti per agenti usa già lo streaming per impostazione predefinita.
2. Usa un endpoint diretto se il provider ne offre unoAlcuni provider pubblicano un host API che aggira la loro CDN proprio per evitare questo limite. Se le chiamate lunghe senza streaming sono inevitabili, serve a questo.
3. Suddividi il lavoroSe una singola chiamata ha davvero bisogno di minuti di ragionamento prima di produrre qualcosa, di solito è più economico e affidabile dividerla in fasi con punti di ripresa.

Articoli correlati

Ultima verifica: 2026-10-01. Scritto a partire da problemi diagnosticati su un gateway compatibile con OpenAI in produzione, non raccolto da altri siti.