Di solito tra te e il modello ci sono tre timeout: quello dell’SDK, quello di un intermediario e la regola del provider sulle chiamate lunghe non in streaming — vince il più breve. Aumentare solo quello dell’SDK è il motivo per cui il problema continua a verificarsi anche dopo aver pensato di averlo risolto.
L’errore
# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
"message":"Streaming is strongly recommended for operations that may take
longer than 10 minutes."}}
# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.Cause e soluzioni in breve
| Causa | Soluzione |
|---|---|
| Una generazione lunga non in streaming | Usa lo streaming. Le risposte lunghe devono essere trasmesse in streaming, non attese. |
| Timeout del client SDK più breve della generazione | Aumentalo, ma aumenta anche il limite dell’intermediario, altrimenti nulla cambia. |
| Un proxy, un bilanciatore del carico o una funzione serverless che limita la richiesta | Individua il limite più breve nella catena: è quello che stai raggiungendo. |
| Connessione accettata, poi nessuna risposta | Un blocco, non una risposta lenta. Limita separatamente il tempo al primo byte. |
Usa lo streaming per tutto ciò che potrebbe durare più di un paio di minuti
Oltre a evitare il limite, lo streaming offre un segnale di attività: l’arrivo dei token indica che il modello sta lavorando, quindi un blocco diventa distinguibile da un semplice avanzamento lento. Con un’unica chiamata bloccante, i due casi sembrano identici finché non scatta il timeout.
Aumenta ogni timeout nella catena, non solo quello dell’SDK
Quasi tutti modificano il client e si fermano lì. Se un reverse proxy o una piattaforma serverless limita la richiesta al di sotto del nuovo timeout del client, quel limite continua a vincere e il sintomo non cambia.
from anthropic import Anthropic
# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)
with client.messages.stream(
model="claude-sonnet-5",
max_tokens=8192,
messages=[{"role": "user", "content": prompt}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)Limita separatamente il tempo al primo byte rispetto alla durata totale
Sono due errori diversi che richiedono due rimedi diversi. Una scadenza breve per il primo byte rileva rapidamente una connessione inattiva; una scadenza totale generosa consente di completare una generazione realmente lunga. Un unico timeout combinato non può fare entrambe le cose.
Rendi sicuri i retry prima di aggiungerli
Una richiesta scaduta dal tuo lato potrebbe essere stata completata a monte. Se il lavoro ha effetti collaterali o vieni addebitato per chiamata, aggiungi l’idempotenza al tuo livello prima di introdurre un ciclo di retry.
Se chiami tramite Kunavo
Kunavo pubblica i propri numeri invece di lasciarti scoprirli: attende al massimo 240 secondi per gli header della risposta upstream e una risposta non in streaming normalmente invia gli header solo quando è completa, quindi una chiamata non in streaming che richiede più tempo non verrà completata tramite il gateway — usa lo streaming. Il limite di 240 secondi si applica solo al tempo fino agli header e viene rilasciato non appena arrivano, quindi non tronca mai uno stream lungo; nient’altro nel gateway limita la durata di uno stream. Ciò che può terminarlo è il silenzio: 300 secondi senza un byte dall’upstream oppure 600 secondi senza un byte sulla connessione verso di te. Le route sincrone per immagini, video e musica mantengono aperta la connessione fino a 540 secondi mentre il rendering termina, all’interno della finestra di 600 secondi, perché i rendering richiedono legittimamente alcuni minuti. Una richiesta che va in timeout prima degli header conta come errore di canale, viene ritentata sul canale successivo del modello quando configurato e viene registrata a costo zero.
Domande frequenti
Una richiesta scaduta viene fatturata?
Su Kunavo, no — le richieste non riuscite vengono registrate a costo zero. La fatturazione diretta da parte di un provider dipende dal fatto che la generazione sia stata effettivamente eseguita.
Perché lo streaming evita il limite?
La risposta inizia entro pochi secondi e la connessione rimane attiva, quindi nessun intervallo singolo di silenzio è abbastanza lungo da attivare un timeout.
Quale dovrebbe essere il timeout del mio client?
Più lungo della tua generazione realistica peggiore, abbinato a una scadenza breve e separata per il primo byte. Un unico timeout combinato lungo trasforma ogni blocco in un’attesa di diversi minuti.
Guide correlate
- Errori di streaming LLM — interruzioni SSE, stream bloccati e utilizzo mancante
- Errore Claude API 529 overloaded_error — cos’è e come superarlo
Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.