APIMODELSAPIMODELS

Claude Code "Stream idle timeout": what it means and how to fix it

Updated 2026-11-19

TL;DR Short answer: the stream stayed open but stopped delivering data, so one of Claude Code's idle watchdogs aborted it and kept whatever had arrived ("partial response received"). Update Claude Code first, since several versions fixed this exact error, then raise CLAUDE_STREAM_IDLE_TIMEOUT_MS if your network or proxy goes quiet for long stretches.

Model page: Claude Opus 5.5 API — pricing, specs and the playground

You may see this error in a few wordings. "API Error: Stream idle timeout - partial response received" is the one most people search for and the title of a large open issue on the Claude Code GitHub repository. The current Claude Code docs describe the same situation as "API Error: The response stopped arriving. The response above may be incomplete.", and list "Stream idle timeout - no chunks received" for a stream that never produced anything.

All of them mean the same thing: the connection was still open, but data stopped arriving for longer than a watchdog allows, so Claude Code cut it rather than hang forever. It is a client-side timer firing, triggered by a quiet stream, which is why it often appears during long thinking phases or on flaky networks and proxies.

The four timers that can end a quiet stream

TimerFires whenDefault / setting
First-byte deadlineNo response headers arrive after the request is sent (direct Anthropic API and Claude Platform on AWS)CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS
Event-level watchdogNo response events parse; arriving bytes, including keep-alive pings, also reset it for a limited time300 seconds; CLAUDE_STREAM_IDLE_TIMEOUT_MS
Byte-level watchdogNo bytes arrive on the wire, keep-alive pings included (direct API, Claude Platform on AWS and gateway connections)180 seconds on the direct API; CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS
Body idle timeoutNo bytes for 5 minutes, counting the wait for headers (other providers)5 minutes; API_FORCE_IDLE_TIMEOUT

How to fix it

1. Update Claude Code with claude update. The changelog shows repeated fixes for this error, including one where the idle timeout failed the request instead of recovering on Bedrock, Vertex and gateway setups, and one for the error after waking a Mac from sleep mid-request.

2. Give quiet streams more room. Set CLAUDE_STREAM_IDLE_TIMEOUT_MS higher, for example 600000 for 10 minutes. Claude Code raises values under 5 minutes to 5 minutes and caps the byte-level watchdog at 30 minutes.

3. Check what sits between you and the API. Corporate proxies, VPNs and some Wi-Fi networks drop idle connections. If the error disappears on another network, that is your cause.

4. Retry the turn. Claude Code keeps the partial output; ask it to continue, or rerun the step. Tool calls and thinking blocks cannot be half-recovered, so a turn that broke inside one has to run again.

How APIMODELS keeps long Claude streams from going quiet

Most stream idle timeouts happen when the model is thinking for a long time and nothing travels down the wire. On APIMODELS, for Claude on /v1/messages, if the upstream has not started answering within 30 seconds we open the stream with HTTP 200 and send an Anthropic ping event every 15 seconds until content arrives, and keep pinging whenever the stream goes quiet afterwards. The Claude Code docs count keep-alive pings as arriving bytes for the byte-level watchdog, which also runs on gateway connections, so a long thinking phase no longer looks like a dead connection.

Pings cannot fix a network that drops the connection outright, and a failure after the stream has begun still reaches you as a stream error. To use it, set ANTHROPIC_BASE_URL to https://api.apimodels.app and ANTHROPIC_AUTH_TOKEN to your APIMODELS key; the Claude Code setup guide below has the full steps.

Quick start

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.apimodels.app",
    "ANTHROPIC_AUTH_TOKEN": "sk_...your_apimodels_key...",
    "ANTHROPIC_MODEL": "claude-opus-5-5",
    "CLAUDE_STREAM_IDLE_TIMEOUT_MS": "600000"
  }
}

cURL

curl https://api.apimodels.app/v1/messages \
  -H "x-api-key: $APIMODELS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "stream": true,
    "messages": [{"role": "user", "content": "Summarise this error log in three bullet points."}]
  }'

Python

import anthropic

# Same Anthropic SDK, pointed at APIMODELS. The SDK already retries 408/409/429/5xx
# with exponential backoff (twice by default); raise it for batch jobs.
client = anthropic.Anthropic(
    base_url="https://api.apimodels.app",
    api_key="sk_...your_apimodels_key...",
    max_retries=4,
    timeout=600,
)

try:
    with client.messages.stream(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Summarise this error log in three bullet points."}],
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
except anthropic.APIStatusError as e:
    # e.status_code: 429 / 500 / 529 ...; the body carries error.type and a request id
    print("failed:", e.status_code, e.response.headers.get("request-id"), e.message)

FAQ

What does "Stream idle timeout - partial response received" mean?

The stream stayed open but stopped delivering data for longer than Claude Code's idle watchdog allows, so Claude Code aborted it and kept the part that had already arrived. Current docs word the same situation as "The response stopped arriving". It is a client-side timer reacting to a quiet stream.

How do I fix the stream idle timeout in Claude Code?

Run claude update first, because several releases fixed this error. Then raise CLAUDE_STREAM_IDLE_TIMEOUT_MS (values under 5 minutes are raised to 5 minutes; the byte-level watchdog caps at 30 minutes), check for proxies or VPNs that drop idle connections, and rerun the turn.

What is CLAUDE_STREAM_IDLE_TIMEOUT_MS?

It is the Claude Code environment variable that sets how long a stream may stay silent before the event-level and byte-level watchdogs abort it, in milliseconds. Claude Code raises values below 5 minutes to 5 minutes and caps the byte-level watchdog at 30 minutes. You can set it in your shell or in the env block of ~/.claude/settings.json.

Does a keep-alive ping stop the stream idle timeout?

It stops the byte-level watchdog, which the Claude Code docs say counts keep-alive pings as arriving bytes, and it resets the event-level watchdog for a limited time. APIMODELS sends an Anthropic ping every 15 seconds while a Claude stream is waiting or quiet. Pings cannot help if the network drops the connection itself.

Related

掲載メディア
APIMODELS on Product HuntAPIMODELS featured on ToolifyAPIMODELS featured on There's An AI For That