Home / Blog / Pricing

Pricing

Claude Code "API Error: The operation timed out": Causes and Fixes

Claude Code shows "API Error: The operation timed out"? Why it happens (headless runs, MCP tool calls, network), the documented timeout settings and fixes.

By Engineer Foodie Desk ✓ Sources checked Nov 4, 2026

8 min read

Error strings quoted from Claude Code GitHub issues #69173 and #93143 (verified Nov 3, 2026, re-checked Nov 4, 2026). Timeout settings and defaults checked Nov 4, 2026 in Claude Code’s environment variables docs, MCP docs and error reference. Every source is listed at the bottom. No affiliate links on this page (how we work).

The exact error: API Error: The operation timed out.

This is the line from GitHub issue #69173 (verified Nov 3, 2026):

API Error: The operation timed out.

And this is the MCP tool-call version, from GitHub issue #93143 (verified Nov 3, 2026), as it shows up in stream-json output:

{"type":"tool_result","is_error":true,"content":[{"type":"text","text":"The operation timed out."}]}

The one-line answer: something waited longer than a timer allowed, and Claude Code gave up. Which timer depends on where you saw it. In the two GitHub reports, one was a headless claude -p run started by a scheduler, and the other was a long MCP tool call that died at about six minutes.

One thing to know before you start changing settings: Anthropic’s error reference, as of Nov 4, 2026, doesn’t list this exact wording. It documents a related message, Request timed out, with its own fixes. So everything below is either from the two issues or from Anthropic’s documented timeout settings, and each line says which.

Where “The operation timed out” shows up

Headless claude -p runs from a scheduler (#69173)

The reporter in #69173 (opened Jun 17, 2026, Claude Code 2.1.179, macOS, AWS Bedrock) ran claude -p from a launchd job. The process stayed alive for “10–20+ minutes”, produced no output, then logged API Error: The operation timed out. The same prompt worked when they ran it interactively. Adding --dangerously-skip-permissions didn’t help, and neither did splitting the prompt into two calls.

GitHub’s bot closed it on Jun 21, 2026 as a duplicate of #61416, whose title says claude -p “does not exit after final text when session used run_in_background=True Bash tools.” That issue was closed as “not planned”. Anthropic didn’t post a cause in either thread, so the honest summary is: headless runs can hang, and the duplicate link points at background Bash tools as one suspect.

Long MCP tool calls that die at about six minutes (#93143)

#93143 (opened Sep 9, 2026, v2.1.266, Linux) is the detailed one. A Streamable HTTP MCP server held a tools/call open while waiting for a human to answer. The call failed with “The operation timed out.” at about 352 to 363 seconds, three times in a row. And that’s with the per-server timeout set to 24 hours and CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0. The reporter had applied every documented setting and the call still died. Picture Ross in “The One Where No One’s Ready”, already in his tux and tapping his watch, except this Ross eventually walks out without you.

A community commenter (not Anthropic staff) traced it to the Bun runtime that Claude Code ships with. Their claim: Bun’s fetch has its own 300-second idle timeout, its error text is TimeoutError: The operation timed out., and it only resets when response bytes arrive. Anthropic didn’t confirm that in the thread. The issue was closed as completed on Sep 15, 2026, with no fix version and no comment saying what changed. Blerg, as Liz Lemon would say. A closed bug with no note about the fix tells you nothing about whether you have the fix.

Plain network or proxy trouble

Claude Code’s error reference has a network version: Request timed out. Check your internet connection and proxy settings, and a server version, Request timed out, which means “The API didn’t respond before the connection deadline” (verified Nov 4, 2026). If your timeout comes with either of those, it’s a network or deadline problem, and the fixes below apply directly.

How to fix it, in order

  1. Check status.claude.com. If there’s an incident, wait it out. (We link it; we don’t claim any live status here.)
  2. Retry once. Per the error reference, the first fix for Request timed out is to retry the request (verified Nov 4, 2026).
  3. Raise API_TIMEOUT_MS if you’re on a slow network or behind a proxy. Per the env vars docs: it’s the time each API request attempt has to receive its response headers. The default is 600000 (10 minutes) and the max is 2147483647. Anthropic says to “Increase this when requests time out on slow networks or when routing through a proxy.” Setting it to 0 removes the limit, which needs v2.1.305 or later, and even then a non-streaming attempt still times out after 300 seconds in a local session (verified Nov 4, 2026).
  4. For slow MCP tools, set a per-server timeout or MCP_TOOL_TIMEOUT. Per the MCP docs, add a timeout field in milliseconds to that server’s .mcp.json entry, for example "timeout": 600000 for ten minutes. MCP_TOOL_TIMEOUT defaults to 100000000 ms (about 28 hours), but for HTTP, SSE and claude.ai connector servers “each request also times out after 60 seconds by default”. Set the variable or the per-server timeout above 60000 to raise that (verified Nov 4, 2026).
  5. Know the MCP idle timeout. CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT aborts a tool call when the server “sends no response and no progress notification” for the idle window. The defaults are 5 minutes for network servers and 30 minutes for stdio. 0 disables it, and it needs v2.1.187 or later (env vars docs, verified Nov 4, 2026). If your server can send progress notifications while it works, that’s the documented signal that it’s still alive. Be aware that #93143 reports a six-minute death even with this set to 0.
  6. For MCP startup timeouts, it’s MCP_TIMEOUT. It covers server startup, defaults to 30000 ms, and the docs give MCP_TIMEOUT=10000 claude as an example. Don’t confuse it with tool-call timeouts.
  7. Check your proxy. Per Claude Code’s network docs, set HTTPS_PROXY if you need a corporate proxy, and test reachability with curl -I https://api.anthropic.com (verified Nov 1, 2026). Claude Code doesn’t support SOCKS proxies.
  8. Run /doctor and /mcp, then report with /feedback. Per the troubleshooting page, /doctor checks your setup, /mcp shows MCP server status, and /feedback reports the problem to Anthropic.

For headless runs like #69173, there’s no documented launchd-specific fix. The issue links to the background-Bash bug, so if your claude -p job starts background processes, that’s the place to look. Keep the job’s log so you can attach it to a report.

What not to do: don’t wrap Claude Code in loops that retry forever with no backoff, and don’t use unofficial “unlimited” relays to dodge timeouts. A timer that fires on a healthy connection is a bug to report, not something to tunnel around.

Timed out vs ECONNRESET vs 529

ErrorUsually meansPost
Operation timed outA timer firedYou’re here
Request timed outNo reply by deadlineYou’re here
ECONNRESETConnection droppedECONNRESET
529 OverloadedAPI busy for all529 overloaded
400Request invalidAPI Error 400

From the Claude Code error reference and issues #69173 and #93143, verified Nov 4, 2026.

If the connection was cut rather than left waiting, read Claude Code ECONNRESET. If it says Overloaded, it’s Claude Code 529 overloaded. If the request came back rejected with a 400, see Claude Code API Error 400.

Does a timeout count against my usage limit?

Not published. Anthropic documents that a 529 doesn’t count against your quota, but says nothing about timeouts either way. For how the session and weekly limits work, see Claude Code usage limits.

Here’s what I’d do

Interactive session timing out? Check status, retry, then raise API_TIMEOUT_MS if you’re behind a proxy. MCP tool dying at five or six minutes? Set a per-server timeout, have the server send progress notifications if it can, and if it still dies, add your case to the issue tracker with your version number, because the documented settings didn’t save the #93143 reporter. Headless claude -p hanging under a scheduler? Check for background Bash processes and file a report with logs.

And if timeouts are wrecking your workday, keep a second tool ready. Our Claude Code alternatives list and AI coding tools compared page have the options with dated prices.

Getting a 403 forbidden rather than a timeout? Claude Code API Error 403 covers “Request not allowed” and access-grant cases.

Blank Claude Code panel or “Error loading webview” in VS Code? That’s a UI failure, not a timeout — see Claude Code Error Loading Webview.

If the API never accepts the socket (ConnectionRefused) rather than timing out, see Claude Code ConnectionRefused.

FAQ

Why does Claude Code say the operation timed out? A timer ran out before a reply arrived; GitHub reports show it on headless claude -p runs and on MCP tool calls that last about six minutes.

What does API Error: The operation timed out. mean in Claude Code? It means Claude Code stopped waiting for a response; Anthropic’s error reference doesn’t list that exact wording, but documents Request timed out with retry and API_TIMEOUT_MS as fixes.

How do I increase the Claude Code timeout? Set API_TIMEOUT_MS for API requests (default 600000 ms), and for MCP tools use a per-server timeout in .mcp.json or MCP_TOOL_TIMEOUT.

Why does my MCP tool call time out at about 6 minutes? GitHub issue #93143 reports that even with a 24-hour per-server timeout and CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0; a community comment blames Bun’s fetch idle timeout, which Anthropic hasn’t confirmed.

Does a timeout count against my usage limit? Not published; Anthropic says 529 errors don’t count against your quota but hasn’t said either way for timeouts.

Is Claude Code down if it keeps timing out? Check status.claude.com for incidents; if there are none, check your network and proxy settings and raise API_TIMEOUT_MS.

Sources

  1. Claude Code GitHub issue #69173 (headless claude -p via launchd, “API Error: The operation timed out.”; closed as duplicate): https://github.com/anthropics/claude-code/issues/69173 (verified 2026-11-03, re-checked 2026-11-04)
  2. Claude Code GitHub issue #61416 (claude -p does not exit with background Bash tools; closed not planned): https://github.com/anthropics/claude-code/issues/61416 (verified 2026-11-04)
  3. Claude Code GitHub issue #93143 (Streamable HTTP MCP tool call times out at about 6 minutes; closed as completed, no fix version stated): https://github.com/anthropics/claude-code/issues/93143 (verified 2026-11-03, re-checked 2026-11-04)
  4. Claude Code environment variables (API_TIMEOUT_MS, MCP_TIMEOUT, MCP_TOOL_TIMEOUT, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT): https://code.claude.com/docs/en/env-vars (verified 2026-11-04)
  5. Claude Code MCP docs (per-server timeout, idle timeout, background tool calls): https://code.claude.com/docs/en/mcp (verified 2026-11-04)
  6. Claude Code error reference (Request timed out, network timeout message): https://code.claude.com/docs/en/errors (verified 2026-11-04)
  7. Claude Code network configuration (HTTPS_PROXY, no SOCKS, curl check): https://code.claude.com/docs/en/network-config (verified 2026-11-01)
  8. Claude Code troubleshooting (/doctor, /mcp, /feedback): https://code.claude.com/docs/en/troubleshooting (verified 2026-11-04)
  9. Anthropic status page: https://status.claude.com (linked, no live status claimed)

Related reading