Claude API Error: The Operation Timed Out — What It Means and How to Fix It (2026)

"API Error: The operation timed out" means a request to Claude hit its deadline before a usable response came back. It is not an authentication or billing error. In Claude Code the per-request limit is API_TIMEOUT_MS, 10 minutes by default, and Claude Code has already retried before showing the message. The fix is usually a network, proxy or gateway setting, not your prompt.

This guide explains what the timeout actually measures, how to tell it apart from the look-alike errors, and which settings to change in which order. Facts about Claude Code and the Claude API below come from the official documentation at code.claude.com and platform.claude.com, checked on 2026-09-26.

What "the operation timed out" means in a Claude API error

A timeout is a clock running out on your side of the connection, not a verdict from the model. Claude Code's official error reference lists the matching entry as Request timed out: the API did not respond before the connection deadline. It gives two typical causes: periods of high load, or the model generating a very large response. The default request timeout is 10 minutes.

Two things follow from that:

• Your credential worked. A bad key fails fast with a 401 or 403 and a JSON error body. A timeout means the request got far enough to be waiting. If you are unsure which one you have, the status-code walkthrough in Anthropic API key not working separates them.
• Something in the path was too slow or went quiet. That can be the model working on a long answer, a slow network, or a proxy or gateway that holds the response until it is complete.

Timeout, 504, "No response from API" and a stalled stream: which one you have

Several messages look similar but point at different layers. Read the exact wording before changing anything.

The distinction that matters most: a 504 timeout_error is the API telling you it timed out, while "the operation timed out" is your client giving up. They have different fixes.

What Claude Code already did before you saw the error

By the time the message appears, Claude Code has used its retry budget. According to the official error reference:

• It retries transient failures, including request timeouts that arrive before any of Claude's response has streamed, up to 10 times with exponential backoff. CLAUDE_CODE_MAX_RETRIES changes that number.
• If no data arrives on a pending stream for 20 seconds, the spinner shows Waiting for API response · will retry in … · check your network. The request has not failed yet at that point.
• On the direct Anthropic API, a streaming request that gets no response headers is aborted at a first-byte deadline (180 seconds on the direct API, 300 seconds elsewhere, plus one second per 32KB of request body) and re-sent once, instead of waiting the full 10 minutes. The docs note this deadline does not run when ANTHROPIC_BASE_URL routes the request through a gateway; on those connections the request waits out API_TIMEOUT_MS.

So "just retry" has partly been done for you. If the error keeps coming back, change something before retrying again.

How to fix it, in order

1. Retry once, then shrink the work

A single timeout during high load often clears on its own. If it repeats on the same task, the official guidance is to break long-running work into smaller prompts: a request that asks for a very large response is exactly the case where the 10-minute limit is reached.

2. Check the network path from the same shell

Run a reachability check from the terminal you launch Claude Code from:

curl -I https://api.anthropic.com

On Windows PowerShell, call curl.exe so the built-in alias is not used. If this fails, fix the network first: VPN, firewall, DNS, or a corporate proxy that needs HTTPS_PROXY set. The two meanings of "proxy" are covered in Claude Code proxy configuration.

If the check succeeds but Claude Code still times out, look for a leftover ANTHROPIC_BASE_URL. When it is set, Claude Code sends model requests there instead of to api.anthropic.com, so a stale value pointing at a relay that is slow or gone produces failures even though the check above passes.

3. Raise the timeout when a proxy or gateway holds responses

Some proxies and gateways buffer a response until generation is complete. With long answers, that silence can outlast the client's patience. The documented fix is to raise the per-request timeout. It is in milliseconds, and the default is 600000:

export API_TIMEOUT_MS=900000

To keep it rather than re-export it each session, put it in the env block of ~/.claude/settings.json (all projects) or .claude/settings.local.json (one project):

{
  "env": {
    "API_TIMEOUT_MS": "900000"
  }
}

Two cautions from the reference: values above 2147483647 overflow the timer and make requests fail immediately, and a positive value under 11 seconds turns the first-byte deadline off. If the first attempt keeps timing out while the retry succeeds, CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS (Claude Code v2.1.242 or later, clamped between 10 seconds and 30 minutes) lengthens the first wait on its own. Which settings layer wins when a key appears twice is explained in Claude Code configuration.

4. Confirm the change took effect

Start a new session after editing, and run /status to see which endpoint and settings sources are in use. A value written in the wrong layer produces no error at all, so check the effective setting rather than the file you edited.

If you call the Claude API directly from your own code

Outside Claude Code, the same error text often comes from your HTTP client or SDK. The Claude API documentation's guidance on long requests is specific:

• For long-running requests, especially those over 10 minutes, use the streaming Messages API or the Message Batches API.
• Avoid a large max_tokens without streaming. Some networks drop idle connections after a variable period, which can make a request fail or time out without any response from Anthropic.
• The official SDKs check that non-streaming Messages requests are not expected to exceed a 10-minute timeout, and they set TCP keep-alive. A direct integration without an SDK can set keep-alive itself.
• A real 504 timeout_error from the API calls for the same remedy: stream the response or move the job to batches.

Streaming does not make generation faster. It keeps bytes moving so no idle timer in the path fires. The latency trade-offs are in LLM API latency.

When a relay or gateway sits in the path

Every hop has its own clock: your client, any corporate proxy, the gateway, and the upstream API. The shortest one decides when the request dies. When you route through a relay endpoint:

• Match the client timeout to the gateway's. A client limit longer than the gateway's only means you wait longer for the gateway's error.
• Prefer streaming end to end. A gateway that forwards stream events as they arrive keeps idle timers quiet; one that buffers them recreates the problem.
• Read the body of the failure. An HTML error page or a non-Claude error format comes from the hop in front of the API, not from the Messages API.

FAQ

Is "API Error: The operation timed out" a problem with my API key?

No. A rejected key fails quickly with a 401 or 403. A timeout means the request was accepted far enough to be waiting for a response that did not arrive in time.

What is the default timeout in Claude Code?

API_TIMEOUT_MS defaults to 600000 milliseconds, which is 10 minutes, and Claude Code retries transient failures up to 10 times before showing an error.

How do I increase the Claude Code timeout?

Set API_TIMEOUT_MS in milliseconds, either exported in the shell or in the env block of a settings file. Raise it when a slow network, proxy or gateway holds responses; do not exceed 2147483647.

Is this the same as an MCP server timeout?

No. MCP server startup has its own limit, MCP_TIMEOUT, 30 seconds by default. An MCP timeout names the server, not the API.

Keeping the endpoint predictable

Most repeated timeouts come from the path, not the model: a proxy that buffers, a gateway with a short clock, or a base URL nobody remembers setting. ROIBest AI serves Claude models behind Anthropic-compatible and OpenAI-compatible endpoints, so the same variables above apply unchanged if you route Claude Code or your own code through it. Set the base URL, credential and timeout in one settings layer and confirm them with /status.