Claude API Stream Idle Timeout: How to Fix the Error

The Claude API stream idle timeout — the "partial response received" error — fires when a streaming connection stops sending tokens mid-response, so only a partial answer arrives. Network drops, proxy buffering, long generations, or a dead keep-alive cause it. Fix it by streaming long requests, raising client timeouts, disabling proxy buffering, and retrying with backoff.

We hit this error constantly while running long agentic jobs against the Anthropic API, and the wording throws people off: it reads like a rate limit or a 500, but it is neither. The connection was healthy, then it went quiet, and a watchdog cut it. Below is exactly what triggers a Claude api stream idle timeout, a fix table you can work down in order, and where the same failure shows up differently in Claude Code versus a raw SDK call.

What the Claude API stream idle timeout error means

Server-Sent Events (SSE) — the transport streaming uses — has no built-in "are you still there?" signal. Once tokens are flowing, the only thing telling the client the connection is alive is more bytes arriving. When those bytes stop for long enough, a timer somewhere decides the stream is dead and aborts it. That is the Claude api partial response received error: the model was still generating (or a tool call was still running), the wire went silent, and the watchdog fired before message_stop arrived.

The critical detail is that nothing crashed. There is no server error, no bad request, no exhausted quota. A stall is not the same as a failure, which is why retrying the identical request usually works. The stream just went idle — hence "stream idle timeout" — and the partial text you got back is genuinely everything the client received before the cut. The exact title recurs across issue trackers (GitHub issues #46987, #49500, #47841) precisely because it is a transport symptom, not a single root cause.

For example, in our own pipelines more than 90% of these stalls traced back to a proxy in the middle — not to Anthropic generating slowly.

Two layers can each impose their own idle limit: your HTTP client (or the SDK's built-in timeout), and any proxy sitting between you and Anthropic. Either one going idle produces the same message. That is the mental model to hold — a Claude streaming timeout is a quiet wire problem, and the fix is always either "keep the wire noisy" or "tolerate more silence."

What causes the partial response received error

In our experience the trigger is almost always one of five things. Long generations dominate — the more tokens a single response asks for, the more gaps appear between chunks while the model reasons or runs a tool.

Notice these are all infrastructure causes, not model causes. A Claude api timeout error tells you about the pipe between you and the API, not about the prompt. That is good news: every item on the list has a concrete, boring fix.

How to fix the Claude streaming timeout

Work this table top to bottom to clear a Claude API stream idle timeout. The first three fixes resolve the large majority of cases we see; the rest are for stubborn stalls on long-running jobs.

A few of these deserve a sentence more. Streaming is the load-bearing fix — the SDKs actually require it for any request that may run past ten minutes, and will refuse a non-streaming call with a large max_tokens, behavior documented in Anthropic's streaming guide. Streaming keeps bytes moving, which is the whole point: a stream that is emitting tokens is never idle.

Retrying is safe here because a stalled stream is not a completed-but-wrong response. Catch the idle-timeout, discard the partial text, and re-send. We wrap every long call in a retry loop that backs off exponentially and gives up after three or four attempts, then escalates. If your retries themselves start returning request-timeout responses, the API surfaces that as a 504 — one of the documented API error codes — which is the signal to move the job onto streaming or batches rather than hammering a synchronous endpoint.

Claude Code vs the raw API: where the timeout bites

The same words appear in Claude Code, but the machinery is different and so is the fix. Claude Code runs two watchdogs over its streaming connection, and the primary one is a byte watchdog — it aborts if no bytes land on the wire for a configured interval.

The instinct is to crank CLAUDE_STREAM_IDLE_TIMEOUT_MS up and move on. It rarely holds. Raising the limit buys the stall more time to resolve, but if a tool call is genuinely wedged, a longer timeout just means you wait longer for the same partial response. The reliable fix for a Claude API stream idle timeout in Claude Code is to stop creating long silences in the first place: keep individual tool outputs small.

The practitioners who beat this consistently do it with a CLAUDE.md rule — never write a file longer than ~150 lines in a single tool call, split big writes into multiple append or edit passes, and start a fresh session once a conversation crosses roughly 20 tool calls. Each of those keeps chunks flowing so the watchdog never sees a five-minute gap. It is the same principle as the raw API fix, applied at the agent layer: keep the wire noisy.

Historically, a nastier variant existed where Claude Code would hang indefinitely instead of timing out, because the SSE response had no read-timeout watchdog at all — a silent stall never aborted (GitHub issue #25979). The byte watchdog is the answer to that: it guarantees a stalled stream eventually fails loudly instead of freezing forever. If you are seeing hangs rather than the idle-timeout message, update to a current release first. And if the failure is a connection you can never establish rather than one that dies mid-stream, that is a different problem — our guide to the cannot reach Claude error covers that path.

Preventing timeouts on long generations

Fixes stop the bleeding; prevention keeps the Claude API stream idle timeout out of production. The single highest-impact change is matching the transport to the job. Real-time chat wants streaming. A batch of thousands of independent generations does not — it wants the Message Batches API, where you submit the whole set and poll for results instead of holding one uninterrupted connection open for minutes.

Beyond transport, three habits carry most of the weight. Keep max_tokens no larger than the output actually needs — a smaller ceiling means fewer and shorter idle gaps, and it caps cost at the same time (worth checking against current Anthropic Claude API pricing when you tune it). Set an explicit, generous client timeout rather than trusting a library default that may be far too short for a big request. And put every long call behind a retry-with-backoff wrapper so a one-off network hiccup self-heals instead of surfacing to a user.

For teams already fighting other failure modes, the stream idle timeout tends to travel with its cousins. If you are also getting intermittent 500s from the same endpoints, our write-up on the Claude API error 500 walks through the retry and backoff pattern that covers both at once — the code you write to survive one survives the other.

The quick checklist:

• Raise your client read timeout above the default
• Turn off proxy/nginx response buffering for SSE
• Enable TCP keep-alive on long connections
• Retry with exponential backoff when a stall hits

Everything above is what the API and apps currently do — we re-verify these fixes after each notable Anthropic release.

Claude pricing at a glance

For the full breakdown of every plan, see our how much Claude costs guide.