Fixing Anthropic SDK APIConnectionError: Request timed out

Why Your Request is Timing Out

Seeing an APIConnectionError: Request timed out usually means your local script stopped waiting before Claude could finish generating a response. By default, the Anthropic SDK sets a 60-second limit. While a minute feels long, it is often not enough time for Claude 3.5 Sonnet or Opus to process massive prompts or write complex, 2,000-word technical documents.

anthropic.APIConnectionError: Request timed out.

Common Culprits

• High Output Volume: Asking for a detailed 3,000-word blog post or a full codebase often exceeds the 60-second window.
• Large Context Windows: Sending a 100k-token document requires several seconds of "pre-fill" time before the first word is even generated.
• Aggressive Proxies: Corporate firewalls or load balancers (like Nginx) often kill connections that stay idle for more than 30 or 60 seconds.
• Network Jitter: High latency on a mobile hotspot or a congested VPN can cause the connection to drop.

Step 1: Bump Up the Default Timeout

The quickest fix is to give the SDK more breathing room. For most production apps, a 2-minute (120s) or 5-minute (300s) timeout is much safer for complex tasks.

Python Configuration

In Python, the timeout argument uses seconds. You can set it globally for the client or override it for a single specific call.

from anthropic import Anthropic

# Increase global timeout to 2 minutes
client = Anthropic(
    api_key="your_api_key",
    timeout=120.0 
)

# Or, set a 5-minute timeout for one heavy request
response = client.messages.create(
    model="claude-3-5-sonnet-20240620",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Analyze these five 50-page PDFs..."}],
    timeout=300.0 
)

Node.js Configuration

The JavaScript SDK uses milliseconds. Multiply your desired seconds by 1,000.

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: 'my_api_key',
  timeout: 120 * 1000, // 120 seconds
});

// Request-specific override (5 minutes)
const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20240620',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Generate a full system architecture.' }],
}, { timeout: 300000 });

Step 2: Align Network Proxies

If you are behind a corporate proxy, your code's timeout might not be the problem. Many proxies have their own internal timers. If your code is set to 300 seconds but your proxy kills connections at 60, you will still see a timeout error.

Ensure your environment variables are active in your terminal:

export HTTP_PROXY="http://your-proxy-server:8080"
export HTTPS_PROXY="http://your-proxy-server:8080"

Pro Tip: If you use Nginx as a reverse proxy, check the proxy_read_timeout setting. It should match or exceed your SDK timeout.

Step 3: Switch to Streaming (The Best Practice)

Streaming is the most robust way to prevent timeouts. Instead of waiting for the entire 4,000-token response to finish, Claude sends data piece-by-piece. This keeps the connection "active" and prevents the network from thinking the request has stalled.

Python Streaming Example

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a long-form research paper."}],
    model="claude-3-5-sonnet-20240620",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

How to Test Your Solution

Don't just wait for the error to happen again. You can verify your settings with these steps:

• Force a failure: Set timeout=0.001. If your code immediately throws an APIConnectionError, you know you're editing the right configuration.
• Test a heavy load: Set the timeout to 120.0 and ask Claude to "Write a 2,000-word essay on the history of computing."
• Check the clock: Use a stopwatch. If the request completes successfully after 75 seconds, your new timeout is working perfectly.

Final Checklist

• Update the SDK: Anthropic frequently improves connection handling. Run pip install -U anthropic or npm install @anthropic-ai/sdk@latest.
• DNS Check: If timeouts happen in less than 1 second, it's likely a DNS issue. Try ping api.anthropic.com to see if your machine can reach the server.
• Retry Logic: The SDK retries twice by default. You can increase this with max_retries=5 if your internet connection is particularly unstable.