AI API Network Errors — ECONNRESET, Timeout, TLS Fix Guide 2026 | AI Error Hub
AI Error Hub/Categories/Network, Connection & TLS Errors
Category Hub

Network, Connection & TLS Errors

ECONNRESET, ETIMEDOUT, TLS handshake failures — the fix for each.

18 documented errors
Network errors are the base of every reliability incident. Before your code sees an HTTP status, a socket must connect, TLS must handshake, DNS must resolve, and packets must flow. When any layer fails, you get errors that look nothing like the provider's documented error catalog. This hub is every network-layer error that shows up when calling AI APIs, and the patterns to handle them reliably.

Errors in this category

Connection errors
ECONNRESET

TCP connection reset by remote host; usually mid-request server-side termination.
ECONNREFUSED

Connection refused; wrong port, service down, or firewall blocking.
ETIMEDOUT_connect

Connection attempt exceeded system timeout; often DNS or routing issue.
EHOSTUNREACH

No route to host; network configuration or DNS pointing to unreachable IP.
socket_hang_up

Node.js-specific ECONNRESET variant; connection closed before response completed.
DNS errors
ENOTFOUND

DNS resolution failed; hostname doesn't resolve to any IP.
EAI_AGAIN

DNS lookup temporarily failed; usually resolver timeout or overload.
DNS_SERVFAIL

Authoritative DNS server returned SERVFAIL; provider DNS misconfiguration.
TLS & SSL errors
tls_handshake_failure

TLS handshake failed; often clock skew, unsupported cipher, or MITM proxy.
SELF_SIGNED_CERT_IN_CHAIN

Certificate chain includes self-signed cert; usually corporate proxy.
CERT_HAS_EXPIRED

Server certificate expired; provider issue, contact them if it persists.
DEPTH_ZERO_SELF_SIGNED_CERT

Server presented a self-signed certificate; usually staging endpoint or MITM.
tls_protocol_version_mismatch

Client and server can't agree on TLS version; upgrade client OpenSSL.
Proxy & network middlebox
proxy_authentication_required

Corporate proxy requires authentication; 407 status.
proxy_connect_tunnel_failed

HTTPS CONNECT tunnel through proxy failed; usually filtering rule.
proxy_header_stripping

Corporate proxy strips or modifies headers, breaking API auth or streaming.
Read/write timeouts
read_timeout_response

Connection succeeded but reading response body exceeded timeout.
write_timeout_request

Sending request body exceeded timeout; usually huge system prompts or attachments.

Related pillar guides

G2. Retry Logic Patterns That Actually Work

Network errors are the canonical retry-worthy failure. This pillar covers the classifier patterns and full retry-with-backoff logic.

G9. Exponential Backoff Explained with Working Code

The math and code for the retry timing that handles network failures without amplifying load.

Related blog posts

Bulletproof Claude API Wrapper (with code)

The wrapper pattern that catches network errors alongside HTTP status errors with a unified retry classifier.

Retry Logic for Claude 429s

The retry decorator that handles ECONNRESET and 429 with the same code path.

Frequently asked questions

Are network errors retryable?

Yes, almost always. ECONNRESET, ETIMEDOUT, socket hang up, EAI_AGAIN — all transient. Use exponential backoff (G9) and retry 3-5 times. The exception: ECONNREFUSED that persists across retries suggests wrong hostname or a hard outage; fail fast.

Why do I see ECONNRESET on the first request after a period of inactivity?

TCP connections in HTTP clients (Node's http.Agent, Python requests session) can be kept alive but silently killed by intermediate load balancers. First request on a dead connection fails with ECONNRESET. Fix: disable keep-alive for AI API calls, or use a client that retries the first ECONNRESET automatically.

How do I fix TLS certificate errors behind a corporate proxy?

Options: (1) install your corporate CA into Node's/Python's trust store, (2) use NODE_EXTRA_CA_CERTS environment variable pointing to the CA bundle, (3) route AI API traffic outside the proxy if policy allows. Never disable cert verification in production — it opens you to MITM attacks.

What's a reasonable timeout for AI API calls?

Connect timeout: 10 seconds. Read timeout: 60-120 seconds for non-streaming (larger for very long responses). For streaming, use inter-chunk timeouts (kill if no bytes for 30 seconds) rather than total timeout.

Why do I sometimes get partial JSON responses that end mid-object?

Almost always ECONNRESET during streaming or read. The provider generated the full response, but the connection dropped before you finished reading it. Retry the whole request — you can't resume from mid-response.

Are proxy errors different from provider errors?

Yes — proxy errors are your infrastructure, not the provider's. 407, tunnel failures, and header stripping issues are all on your side. Isolate by testing the same request from a different network (mobile hotspot, cloud shell). If it works elsewhere, it's your proxy.

Should I use IPv4 or IPv6 for AI API calls?

Most providers work equally well over both. Some corporate networks have inconsistent IPv6 support; prefer IPv4 (via node --dns-result-order=ipv4first or Python's family parameter) if you see intermittent connect failures on IPv6-preferring hosts.