anthropic.APITimeoutError: Request timed out.
Răspunsul nu a venit în timpul permis de client (`timeout`). Apare la răspunsuri lungi, la un timeout setat prea mic sau la rețea lentă. Mărește `timeout`, păstrează reîncercările, folosește streaming pentru răspunsurile lungi și cere răspunsuri mai scurte.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Clientul SDK-ului așteaptă răspunsul doar un anumit timp (timeout, implicit 10 minute la anthropic și openai). Dacă în acest timp nu primește răspunsul complet, renunță și aruncă APITimeoutError. APITimeoutError e un caz particular de APIConnectionError, deci un except anthropic.APIConnectionError le prinde pe amândouă.
Cauza obișnuită e un timeout pus prea mic de tine (de exemplu timeout=5.0, „ca să nu stea aplicația”), combinat cu un răspuns lung: un model generează câteva zeci sau sute de tokeni pe secundă, deci un text de câteva mii de tokeni durează. Alte cauze: un max_tokens foarte mare, efort de raționament mare, rețea lentă.
SDK-ul reîncearcă automat și timeout-urile, dar dacă cererea e prea lungă pentru timeout-ul ales, va expira la fiecare încercare. Pentru răspunsuri lungi, streaming-ul e soluția bună: primești textul pe măsură ce se generează, iar conexiunea rămâne activă.
De ce apare: cauzele frecvente
1Timeout prea mic pentru un răspuns lung
client = anthropic.Anthropic(timeout=5.0, max_retries=0)
r = client.messages.create(model=MODEL, max_tokens=4000, messages=mesaje)client = anthropic.Anthropic(timeout=60.0, max_retries=2)
r = client.messages.create(model=MODEL, max_tokens=4000, messages=mesaje)Un timeout realist și reîncercările active acoperă răspunsurile lungi și sughițurile de rețea.
2Răspuns foarte lung fără streaming
r = client.messages.create(model=MODEL, max_tokens=30000, messages=mesaje)with client.messages.stream(model=MODEL, max_tokens=30000, messages=mesaje) as stream:
for text in stream.text_stream:
print(text, end="")Cu streaming, textul vine pe bucăți și utilizatorul vede progresul, în loc să aștepte tot răspunsul.
3Timeout diferit doar pentru o cerere
client = anthropic.Anthropic(timeout=600.0) # pentru toate cererileclient = anthropic.Anthropic(timeout=20.0)
raport = client.with_options(timeout=300.0).messages.create(**cerere_lunga)with_options îți permite un timeout mai mare doar pentru cererile care chiar au nevoie.
Repară eroarea, direct în pagină
Programul de mai jos generează un rezumat de contract și se oprește cu anthropic.APITimeoutError: Request timed out.: clientul are timeout=2.0 și max_retries=0 (în simulator, prima încercare expiră). Repară crearea clientului cu timeout=60.0 și max_retries=2. Programul afișează rezumatul.
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic(timeout=2.0, max_retries=0)
r = client.messages.create(
model=MODEL,
max_tokens=600,
messages=[{"role": "user", "content": "Rezumă contractul de închiriere: durată 12 luni, chirie 2.500 lei, garanție 2 luni."}],
)
print(r.content[0].text)Contract de închiriere pe 12 luni, cu chirie lunară de 2.500 lei și garanție egală cu două chirii.
Indiciu
Ambele valori se dau la anthropic.Anthropic(...).
Reparația
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic(timeout=60.0, max_retries=2)
r = client.messages.create(
model=MODEL,
max_tokens=600,
messages=[{"role": "user", "content": "Rezumă contractul de închiriere: durată 12 luni, chirie 2.500 lei, garanție 2 luni."}],
)
print(r.content[0].text)De ce merge
Un rezumat de contract poate dura zeci de secunde, iar două secunde nu ajung. Cu timeout=60.0, clientul îi lasă modelului timp să termine, iar max_retries=2 reia automat cererea dacă o încercare expiră totuși (aici, prima). Pentru texte foarte lungi, streaming-ul ar fi pasul următor.
Alte forme ale mesajului
openai.APITimeoutError: Request timed out.
Cum o eviți pe viitor
- Alege timeout-ul după tipul cererii: scurt pentru chat, mai lung pentru documente mari.
- Folosește streaming pentru răspunsurile lungi.
- Pune un
max_tokenspotrivit, nu cel mai mare posibil. - Prinde
APITimeoutErrorși oferă utilizatorului un mesaj clar sau o variantă mai scurtă.
Întrebări frecvente
Plătesc pentru o cerere care a expirat?
Se poate ca serverul să fi generat o parte din răspuns înainte ca clientul să renunțe, iar tokenii generați se facturează. Încă un motiv să nu pui un timeout prea mic.
Care e diferența față de APIConnectionError?
APITimeoutError e un tip de eroare de conexiune: conexiunea a existat, dar răspunsul n-a venit la timp. APIConnectionError acoperă și cazurile în care conexiunea nici nu s-a deschis.
Erori înrudite
anthropic.APIConnectionError: Connection error. Cererea nu a ajuns la server sau răspunsul nu a ajuns înapoi: problemă de rețea, DNS, proxy, firewall sau o întrerupere scurtă. Verifică conexiunea și setările de proxy, lasă SDK-ul să reîncerce (`max_retries`) și prinde `APIConnectionError` cu un mesaj prietenos. anthropic.InternalServerError: Error code: 529 - {'type': 'error', 'error': {'type': 'overloaded_error', 'message': 'Overloaded'}} Serverele Anthropic sunt temporar suprasolicitate; nu e vina codului sau a contului tău. Reîncearcă după o pauză (SDK-ul o face automat de 2 ori), iar pentru aplicațiile importante pregătește un plan B: alt model sau alt furnizor, plus un mesaj prietenos pentru utilizator. anthropic.BadRequestError: Error code: 400 - max_tokens: 200000 > 128000, which is the maximum allowed number of output tokens for claude-haiku-5-5 Ai cerut un `max_tokens` mai mare decât poate genera modelul într-un răspuns. Pune o valoare sub limita modelului, pe măsura răspunsului de care ai nevoie (de exemplu 1000–4000 pentru texte obișnuite), și verifică `stop_reason` ca să știi dacă răspunsul a fost tăiat. Învață Aplicații AI cu LLM de la zero, cu exerciții la fiecare lecție
Curs Aplicații AI cu Claude și OpenAI: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 8 lecții sunt gratuite.
