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.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
APIConnectionError e diferită de erorile cu cod (400, 401, 429, 529): nu există niciun răspuns HTTP de la server. SDK-ul nu a reușit să deschidă sau să păstreze conexiunea. De aceea excepția nu are status_code.
Cauzele frecvente: internet întrerupt sau instabil (Wi-Fi, VPN), un proxy de firmă care blochează domeniul API-ului sau cere configurare, un firewall pe server care nu permite conexiuni ieșite, un base_url greșit, probleme de certificat SSL în rețele corporate sau o întrerupere scurtă pe drum. Dacă eroarea apare mereu, problema e de configurare; dacă apare rar, e o problemă temporară de rețea.
SDK-urile reîncearcă automat erorile de conexiune (implicit de 2 ori). Dacă le-ai dezactivat cu max_retries=0, orice sughiț de rețea devine excepție. În traceback, sub APIConnectionError găsești de obicei eroarea originală (ConnectError, SSLError), care îți spune cauza exactă.
De ce apare: cauzele frecvente
1Reîncercările dezactivate
client = anthropic.Anthropic(max_retries=0)client = anthropic.Anthropic(max_retries=3)Întreruperile scurte de rețea trec la a doua sau a treia încercare, fără ca utilizatorul să observe.
2Proxy de firmă neconfigurat
$ python app.py
anthropic.APIConnectionError: Connection error.$ export HTTPS_PROXY="http://proxy.firma.ro:8080"
$ python app.pyÎn multe rețele de firmă, conexiunile spre internet trec obligatoriu printr-un proxy, pe care SDK-ul îl citește din HTTPS_PROXY.
3Eroarea de rețea arătată clientului
r = client.messages.create(**cerere)try:
r = client.messages.create(**cerere)
except anthropic.APIConnectionError:
return "Avem o problemă de conexiune. Încearcă din nou peste un minut."Chiar și cu reîncercări, o pană de rețea mai lungă poate apărea; clientul trebuie să primească un mesaj clar.
Repară eroarea, direct în pagină
Programul de mai jos se oprește cu anthropic.APIConnectionError: Connection error.: în simulator, primele două încercări pică din cauza rețelei, iar clientul are max_retries=0. Repară crearea clientului cu max_retries=3. Programul afișează răspunsul.
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic(max_retries=0)
r = client.messages.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": "Cum îmi resetez parola la contul de client?"}],
)
print(r.content[0].text)Apasă pe „Am uitat parola” în pagina de autentificare și urmează linkul primit pe e-mail.
Indiciu
Reîncercările automate ale SDK-ului se setează la crearea clientului.
Reparația
import anthropic
MODEL = "claude-haiku-5-5"
client = anthropic.Anthropic(max_retries=3)
r = client.messages.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": "Cum îmi resetez parola la contul de client?"}],
)
print(r.content[0].text)De ce merge
O întrerupere scurtă de rețea e exact cazul pentru care SDK-ul are reîncercări automate: cererea e repetată după o pauză scurtă și, de obicei, trece. Cu max_retries=0, prima pană devenea excepție. Cu max_retries=3, primele două încercări eșuate sunt reluate, iar a treia reușește. Într-o aplicație reală, adaugi și un except anthropic.APIConnectionError pentru penele mai lungi.
Alte forme ale mesajului
openai.APIConnectionError: Connection error.
Cum o eviți pe viitor
- Păstrează reîncercările automate ale SDK-ului active.
- Prinde
APIConnectionErrorseparat de erorile cu status și afișează un mesaj prietenos. - Pe servere, verifică din timp că sunt permise conexiunile ieșite spre domeniile API-urilor (și proxy-ul, dacă e cazul).
- Loghează și cauza originală (
e.__cause__), ca să deosebești o pană de rețea de o configurare greșită.
Întrebări frecvente
De ce nu are status_code?
Pentru că serverul nu a apucat să răspundă. Codurile de status vin într-un răspuns HTTP; aici conexiunea a eșuat înainte.
Merge de pe laptop, dar nu de pe server. De ce?
Probabil serverul nu are voie să facă conexiuni ieșite spre API (firewall, rețea privată) sau are nevoie de proxy. Testează de pe server cu curl https://api.anthropic.com.
Erori înrudite
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. anthropic.RateLimitError: Error code: 429 - rate_limit_error: Number of request tokens has exceeded your per-minute rate limit Ai trimis prea multe cereri sau prea mulți tokeni într-un minut pentru limita contului tău. Eroarea e temporară: așteaptă cât spune antetul `retry-after` și reîncearcă. Lasă SDK-ul să reîncerce (`max_retries`, implicit 2) sau scrie un backoff exponențial cu jitter, și rărește cererile. 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. Î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.
