Claude API Timeout Configuration Settings Guide

When you call the Claude API, three different timeout clocks can cut off your request before it finishes: your HTTP client's timeout, any proxy or load balancer sitting between you and the API, and the model's own generation time on longer completions. Getting timeout configuration right means setting all three deliberately instead of relying on library defaults, which are usually far too short for anything beyond a quick chat reply.

This matters most when you're generating long outputs (large JSON documents, multi-step reasoning, big code files) or using extended thinking, where a single request can legitimately take 60–120+ seconds. If your client gives up at the default 10 or 30 seconds, you'll see connection-reset errors that look like the API is broken when it's actually your timeout setting that's wrong.

Where timeouts actually come from

Before changing any config, know which layer is cutting you off:

• HTTP client timeout — the library you're using (axios, fetch, requests, httpx, Go's net/http) has a default read/connect timeout, often 5–30 seconds.
• Reverse proxy / load balancer — nginx, an API gateway, or a cloud load balancer in front of your backend may enforce its own idle timeout, commonly 30–60 seconds.
• Serverless platform limits — AWS Lambda, Vercel Functions, and Cloudflare Workers all impose hard execution ceilings (from 10 seconds on some free tiers up to 15 minutes on Lambda with configuration).
• Model generation time — longer outputs and larger context windows take longer to generate, independent of network latency.

A request can fail at any of these layers, so a single "increase the timeout" fix in one place often isn't enough.

Setting the HTTP client timeout

Set an explicit timeout rather than trusting the default. In JavaScript with fetch, use AbortController:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 120000); // 120s

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-5",
    max_tokens: 4096,
    messages: [{ role: "user", content: "Summarize this contract." }]
  }),
  signal: controller.signal
});

clearTimeout(timeout);

In Python with httpx:

import httpx

client = httpx.Client(timeout=httpx.Timeout(120.0, connect=10.0))

Setting connect and read timeouts separately is worth doing — a slow connection setup and a slow generation are different problems, and you may want to retry one but not the other.

Configuring proxy and gateway timeouts

If requests pass through nginx, an API gateway, or a cloud load balancer, check the idle/proxy timeout independently of your application code. In nginx:

proxy_read_timeout 180s;
proxy_connect_timeout 10s;
proxy_send_timeout 30s;

For AWS API Gateway, the hard cap is 29 seconds regardless of what you configure upstream — if you're proxying Claude API calls through it for long completions, you'll need to move to a different architecture (direct Lambda function URLs, or streaming responses) rather than fighting the limit.

Serverless timeout limits

Serverless platforms are the most common place teams get bitten by timeout mismatches:

| Platform | Default | Configurable max | |---|---|---| | AWS Lambda | 3s | 900s (15 min) | | Vercel Functions | 10s (Hobby) | 300s (Pro/Enterprise) | | Cloudflare Workers | CPU-time limited, not wall-clock | ~30s typical for I/O-bound |

If you're building a backend that calls Claude and deploying on one of these, raise the function timeout explicitly in its config (timeout in serverless.yml, maxDuration in Vercel's vercel.json) and make sure it's higher than your HTTP client timeout — otherwise the platform kills the function before your client even times out gracefully.

Streaming avoids most timeout problems

The most reliable fix for long-running completions isn't a bigger timeout — it's switching to streaming. With streaming, the connection stays open and tokens arrive incrementally, so proxies and load balancers see continuous traffic instead of a long silent gap, which avoids idle-timeout kills entirely.

const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-5",
    max_tokens: 4096,
    stream: true,
    messages: [{ role: "user", content: "Write a detailed migration plan." }]
  })
});

Even with streaming, keep a generous idle timeout (60–90s) between chunks — a slow first token on a complex prompt shouldn't trigger a false timeout.

Retries and backoff, not just longer timeouts

Increasing timeouts indefinitely isn't a strategy — pair a reasonable timeout with retry logic for transient failures:

async function callWithRetry(fn, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === attempts - 1 || err.name !== "AbortError") throw err;
      await new Promise(r => setTimeout(r, 2 ** i * 1000));
    }
  }
}

Only retry on timeout or 5xx errors — never blindly retry on 4xx, since that usually means a request problem that a retry won't fix.

Simplifying timeout handling with SubToAPI

If you're routing traffic through your own backend already, SubToAPI gives that backend a stable HTTPS endpoint with streaming support built in, so you don't have to separately tune proxy and gateway timeouts for long Claude completions — the streaming connection handles it the same way described above. It works with your existing Claude access: generate a sub_live_... key in the dashboard and call /v1/messages the same way you'd call the standard Messages API, with a free trial to test timeout and streaming behavior against your own workloads before committing to a plan. See the quickstart and streaming docs for exact request shapes.

Best practices summary

• Set explicit client timeouts — never rely on library defaults for anything beyond trivial prompts.
• Separate connect timeout from read timeout so you can diagnose which is failing.
• Check every layer in the chain: client, proxy, serverless platform, and gateway.
• Prefer streaming for long completions instead of raising timeouts indefinitely.
• Add retry with exponential backoff for timeout and 5xx errors only.

FAQs

What's a safe default timeout for Claude API requests? 30 seconds for short conversational replies, 120–180 seconds for longer generations (large JSON, long-form writing, extended thinking). Adjust based on your typical max_tokens and observed latency.

Why do I get connection errors on long completions even with a high client timeout? A proxy or load balancer between you and the API often has its own shorter idle timeout that fires first. Check nginx, API gateways, and serverless platform limits independently of your application code.

Does streaming eliminate the need to configure timeouts? No, but it reduces the risk of idle-timeout kills since data flows continuously. You should still set a reasonable timeout for the gap before the first token and between chunks.