Claude API Stream Idle Timeout: Causes and How to Fix It

A Claude API stream idle timeout means your streaming request sat idle — no new bytes arriving — for longer than a client, proxy, or gateway would tolerate, so the connection was closed mid-generation and you received only a partial response. It is a network and client-side timeout, not a Claude outage, and it is fixable.

Streaming behaviour and client timeout defaults verified 31 July 2026 against Anthropic's streaming documentation.

If you have seen an error like stream idle timeout - partial response received, the response usually started fine, then stalled, and your code (or something between your code and Anthropic) gave up waiting. The tokens that already arrived are real; the rest never made it because the connection closed first. The good news: once you understand where the gap comes from, the fixes are straightforward and mostly about configuration, not luck. These fixes apply across Claude's current lineup — the latest models include Claude Opus 5 and Claude Sonnet 5 — and this guide is reviewed regularly so the steps stay accurate.

What the Claude API Stream Idle Timeout Error Means

A watchdog fired. Your HTTP client or an intermediary resets a timer on every arriving byte; when the silence between chunks outlasts that timer, the connection is torn down mid-generation. It is a read timeout, not a total-duration one.

The Claude API stream idle timeout is best understood as a watchdog firing. When you make a streaming request, the model sends tokens as it produces them over a long-lived HTTP connection using server-sent events. Your HTTP client — or an intermediary such as a proxy, load balancer, or serverless gateway — keeps a timer that resets every time new bytes arrive. If too much time passes with no new bytes, that timer expires and the connection is torn down. Because some output had already streamed, you are left holding a partial response instead of a clean success or a clean error.

This is a read or idle timeout, not a total-duration timeout. A request can run for a long time without tripping it, as long as bytes keep flowing. What trips it is a long silent gap between chunks. That distinction matters, because it points the fix at the gap, not at the overall length of the request.

It is also worth being precise about blame. A Claude API stream idle timeout is a client-side or network-side condition. The model is often still working when the connection drops; the classifiers, capacity, and generation are all fine. That is different from a server-side overloaded_error — if you are chasing capacity problems instead, our guide to the Claude 529 error covers that failure mode, and it is not what this error is telling you.

Why the Timeout Happens

Long generations, extended thinking pausing before the first visible token, a conservative default read timeout, a proxy or serverless gateway with its own shorter limit, an unstable network, or simply not streaming at all. Most failures combine several.

Several conditions push a request toward this failure, and most jobs that hit it combine more than one.

Long generations and large max_tokens. The bigger the requested output, the longer the model runs and the more chances there are for a slow patch in the stream. Anthropic explicitly recommends against setting a large max_tokens value on a non-streaming request for exactly this reason — the whole response has to finish before any bytes return, which invites a timeout. If a request will produce a lot of tokens, that is precisely the shape most likely to stall a fragile connection.

Extended thinking. When a model reasons before it answers, it can spend real wall-clock time thinking before it emits its first visible output token. To a naive idle timer, that upfront reasoning looks like a dead connection — a long pause with nothing arriving. If you are pushing hard on reasoning-heavy prompts, Claude's extended thinking is a common trigger for the silent gap that fires the watchdog.

A short client read or idle timeout. Many HTTP libraries ship with a conservative default read timeout. That default is fine for quick request/response calls but far too tight for a streaming generation that legitimately pauses between chunks. When the default is shorter than the gaps your workload produces, you get an idle timeout even though nothing is actually broken.

An intermediary with its own limit. This is the sneaky one. Proxies, API gateways, ingress controllers, load balancers, and serverless platforms frequently impose their own idle or read timeouts, and those limits can be much shorter than what your application code allows. Your client might be willing to wait ten minutes, but a gateway in front of it may cut the stream at a fixed interval regardless. Serverless functions add a hard maximum execution duration on top of that.

Unstable networks. Some networks drop idle connections after a variable period of time, which can cause the request to fail without ever receiving a complete response. Mobile links, VPNs, and corporate networks are notorious for this.

Not streaming a long request at all. If you send a big job as a plain non-streaming call, the entire response must complete before a single byte returns. That maximizes the window in which a timeout — yours or an intermediary's — can strike.

How to Fix the Claude API Stream Idle Timeout

Three fixes carry most of the load: stream the request so the connection never goes silent, raise your client's read timeout so legitimate pauses are tolerated, and audit every proxy, gateway and serverless limit sitting in front of your code.

Here are the fixes, roughly in order of impact. If you want the short version, start with these three:

• Stream the request so the connection never goes silent long enough to trip a watchdog.
• Raise your client's read/idle timeout so a legitimate pause between chunks is not mistaken for a dead connection.
• Audit every proxy, gateway, and serverless limit in front of your code for a shorter timeout of its own.

Then work through the full list below.

1. Stream the request. Using the streaming Messages API is the single most effective fix for a Claude API stream idle timeout, and it is Anthropic's official recommendation for long-running requests. Streaming sends tokens as they are produced, which keeps the connection active and busy instead of silent. A stream that is constantly delivering small chunks rarely goes idle long enough to trip a watchdog. Anthropic's streaming Messages API documentation shows the exact request shape; in practice it is one flag plus consuming an event stream. For any long or high-max_tokens request, this alone resolves most timeouts.

2. Increase your client's read/idle timeout. Whatever HTTP client or SDK you use, raise the read timeout so it tolerates gaps between chunks. The official SDKs default to a generous window and validate that non-streaming requests are not expected to exceed a roughly 10-minute limit, but if you are on a hand-rolled HTTP client, its default is probably far shorter — bump it up so a legitimate pause is not mistaken for a dead connection.

3. Use the official SDK's streaming helpers. Rather than hand-parsing server-sent events, lean on the Anthropic SDKs. They handle the stream for you and expose a final-message helper — stream.get_final_message() in Python, stream.finalMessage() in TypeScript — that consumes the whole stream and hands you the complete Message object, identical to a non-streaming result. You get streaming's timeout resilience without writing accumulation logic yourself. If you are new to the SDKs, start with our Claude API getting started guide. If enabling streaming immediately throws ReferenceError: ReadableStream is not defined, that is a missing Web Streams global in your runtime rather than a timeout — our guide to the ReadableStream is not defined error covers the fix.

4. Check your intermediaries. Audit every hop between your code and Anthropic: reverse proxies, API gateways, load balancers, ingress timeouts, and serverless function limits. Raise their idle and read timeouts, and make sure they actually forward a streaming response chunk by chunk instead of buffering the whole thing. For direct integrations, Anthropic also suggests enabling a TCP socket keep-alive, which reduces the impact of idle-connection drops on some networks.

5. Handle partial responses gracefully. Assume a timeout will eventually happen and detect it. When you catch a truncated stream, retry with exponential backoff rather than immediately hammering the endpoint. Where possible, make the retry idempotent so a re-run does not double-charge side effects. This is the same backoff discipline you would apply to a Claude Code rate limit error — treat the timeout as a transient failure and recover from it.

6. Reach for keep-alive and Batches for very long jobs. For genuinely huge, non-interactive workloads, keep-alive tuning and reconnection patterns help, but the more resilient answer is the Message Batches API, which lets you poll for results instead of holding one uninterrupted connection open.

Cause, Symptom, and Fix at a Glance

Each failure has a distinctive shape. A hang with no output points at a non-streamed long generation; a cut at a suspiciously round interval points at an intermediary; intermittent partials point at the network. Match the symptom before changing settings.

This table maps each cause to what it looks like in practice and the fix that addresses it.

Handling Partial Responses Without Losing Work

A partial response is a truncated success, not garbage. The trap: mid-stream errors arrive inside a 200 response as stream events, so a client that checks only the status code records a failed stream as a finished one.

A partial response is not garbage — it is a truncated success. When a Claude API stream idle timeout fires mid-stream, keep the tokens you already received and decide whether to retry the whole request or continue from where it stopped. For most use cases a clean retry is simplest and safest, especially if the request is idempotent.

One important subtlety: when you stream, an error can arrive after the API has already returned a 200 status. Mid-stream errors travel as error events inside the stream rather than as a normal HTTP error, so a naive client that only checks the initial status code will treat a failed stream as a success. Anthropic's error reference documents this behavior, and the fix is to inspect stream events for errors, not just the response code. Build your consumer so it can tell the difference between "the model finished" and "the stream ended early."

This exact trap caught us on our own long-form generation jobs. An early version of our reader trusted the 200 and stored whatever text it had accumulated, so a stream that died partway through was silently saved as if it were a finished piece — the failure only showed up later as oddly truncated content with no error anywhere in our logs. What fixed it for good was leaning on the SDK's final-message helper instead of our own accumulation loop, so a stream that ends early raises rather than quietly handing back half an answer we would mistake for the whole thing.

If your workload involves tool calls, the same care applies — a stream that carries Claude tool use blocks can be truncated just like a text stream, so validate that every tool-use block you received is complete before acting on it.

When to Use Batches Instead

If nobody is watching the response render, stop fighting the connection. The Message Batches API replaces a long-lived stream with submit-and-poll, so there is no idle window to trip. Keep streaming for interactive work; batch the overnight tier.

If you find yourself fighting idle timeouts on background jobs that no human is waiting on, stop fighting the connection and change the shape of the work. The Message Batches API lets you submit requests and poll for results, so there is no long-lived stream to keep alive and therefore no Claude API stream idle timeout to hit at all. It is the right tool for bulk generation, offline evaluation, and any workload where a few minutes of latency does not matter. Interactive, user-facing requests should still stream; batch is for the heavy non-interactive tier. Because batch requests are priced differently, it is worth checking the Claude API pricing before you move a large volume over.

The decision is simple. If a user is watching a response render, stream it and tune your timeouts. If a queue is processing thousands of prompts overnight, batch them and poll. Most production systems end up using both, each for the workload it fits.

If you are wiring up the streaming side for the first time, our Claude streaming API guide walks the event schema and the accumulation helper that keeps long outputs from timing out.

Streaming becomes mandatory once your reply gets long: Claude API max_tokens explains the output ceiling, the per-model caps, and why anything above ~16K must be streamed.