Claude Code Request timed outエラー — 原因と対処法

Claude CodeでRequest timed outと表示されるのは、APIへのリクエストが接続デッドラインまでに応答を返さなかったサインです。デフォルトのリクエストタイムアウトは10分。高負荷時や、モデルが非常に長い応答を生成している最中に起きます。

ただし、似た見た目のメッセージが複数あり、効く対処はそれぞれ違います。最初に確認したいのは、画面に出ている文言がどれに当たるかです。

画面の文言から見当をつける

タイムアウト系のメッセージは、いつ失敗したかで名前が変わります。公式のエラー一覧にある文言を、応答の進み具合の順に並べると次のとおりです。

Request timed outは何を意味するか

Claude CodeがAPIへ送ったリクエストへの応答が届かないまま、設定されたタイムアウト値を超えたときに出るエラーです。既定値は600,000ミリ秒、つまり10分です。

Request timed out

このエラーはネットワーク断とは別物です。接続自体は成立しているものの、応答が時間内に返ってこない状態を指します。メッセージに「your internet connection」への言及が付く場合は、ネットワーク側の問題として扱われます。

手元のClaude Code(v2.1.286で確認)では、挙動を後から追うためのデバッグログを次のように取れます。claude --helpの出力に、ログの書き出し先を指定する--debug-file <path>が載っています。

claude --version
# 2.1.286 (Claude Code)
claude --debug-file ./claude-debug.log

--debug-fileを指定するとデバッグモードが暗黙に有効になります。再現性のないタイムアウトは、発生時刻とログの時刻を突き合わせると、単発か連続かを判断しやすくなります。ログにはプロンプトの内容やパスが含まれうるので、共有する前に中身を確認してください。

429・overloadedとは何が違うか

似た場面で出るエラーに429(レート制限)と529 Overloadedがあります。3つは出る場面も対処もそれぞれ異なります。

429とoverloadedの詳しい切り分けと回復手順はClaude rate limitエラーの対処にまとめています。Request timed outは、この2つとは別軸の「時間切れ」の問題です。

自動リトライはどこまで走るか

Claude Codeは一過性の失敗を最大10回、指数バックオフで自動リトライします。それでも解決しなければ、そこで初めてエラーを表示します。リトライの対象になるのは、サーバーエラー、overloadedな応答、そして応答がまだ何も届いていない段階のタイムアウトです。

目の前に出たRequest timed outは「最初の失敗」ではなく、リトライを使い切った末の結果です。裏側では最大10回のバックオフがすでに走っています。この表示を見てすぐ連投しても、同じ条件なら同じ結果になりやすい点は頭に置いてください。

1つめの表示は、データが再開するかリトライが成功すれば自然に消えます。毎回この表示が出るなら、単発の遅延ではなくネットワーク側の問題として扱うのが適切です。advisorに相談している最中だけは、長い審査で無通信になりうるため、表示までのしきい値が20秒ではなく90秒になります。

リトライ中の表示にも読みどころがあります。ラベルは最初の試行で原因を特定できる失敗(ネットワーク断、TLSハンドシェイク失敗、レート制限)ではその理由を出し、それ以外では最初はAPI errorと出ます。v2.1.198以降は3回目の試行で具体的な理由に切り替わります。

v2.1.284より前は、Claudeが考え終えたあと、テキストやツール呼び出しを始める前にサーバーエラーやoverloadedが返ると、そこでターンがエラー終了していました。現在は、その地点のサーバーエラーを最大2回までリトライします。古いバージョンで原因不明の失敗が多いと感じる場合は、アップデートで挙動が変わる箇所です。

応答が途中で切れた場合は別のメッセージになる

Claudeがテキストやツール呼び出しを1つ書き終えたあとに途切れた場合は、別の通知になります。思考を終えて書き始めたあとも同じです。「Response incomplete」の通知がこれに当たり、末尾にThe response above may be incomplete.が付きます。前半はConnection lost mid-responseやThe response stopped arrivingなどです。

Request timed outが指すのは、応答が始まる前の段階の時間切れです。テキストが流れ始めただけの段階なら、同じリクエストが再送されます。2つは原因も見分け方も別物なので、表示を読んでから対処を選んでください。

リトライされない失敗との違い

一過性の失敗は自動リトライの対象ですが、リトライしない失敗もあります。代表例がTLS証明書の検証エラーです。社内プロキシによる証明書の差し替え、NODE_EXTRA_CA_CERTSの未設定、証明書の期限切れが原因のときは、最初の試行でエラーを返します。設定を直さない限りリトライしても解決しないためです。

なお、TLSのハンドシェイク自体のタイムアウトのような一過性の条件は、リトライされます。つまり「TLS関連のエラーは全部リトライなし」ではありません。

Request timed outが繰り返し出るのに、この即時失敗のパターンが見られない場合は、証明書ではなく応答遅延側を疑う材料になります。もう一つのリトライなしの例は、応答がすべて届いたあとに接続が切れた場合です。このときは完全な応答が保持され、ターンは通常どおり終わります。

タイムアウトを調整する

タイムアウト自体の長さと、リトライ回数は環境変数で変更できます。

export API_TIMEOUT_MS=1200000

API_TIMEOUT_MSの最大値は2147483647です。これを超える値はタイマーが溢れ、リクエストが即座に失敗します。極端な値を入れる前に、この上限だけは確認してください。

CLAUDE_CODE_RETRY_WATCHDOGはCIジョブのような無人セッション向けです。標準速度のリクエストが、支出上限やクレジット枯渇を伝える429を受けた場合は、v2.1.239以降、無制限リトライにはならず即座に失敗します。待ち続ければ回復する種類のエラーだけを粘り強く待つ設計です。

対話セッションで有効にすると、詰まったリクエストに長時間張り付いたまま気づきにくくなります。無人運用で回復を待ちたい場面に限る設定として扱うのが妥当です。環境変数の全体像はClaude Code環境変数リファレンスで確認できます。

設定は、exportのほか、settings.jsonのenvにも書けます。社内プロキシ経由の場合はClaude Codeプロキシ設定の手順と合わせて見てください。

ストリームが固まって見えるときの監視タイマー

応答の生存確認には、役割の違う4つのタイマーが独立して動いています。表示上はどれも「応答が来ない」に見えますが、止まる層が違うので、どれが働いたかを知ると原因を絞れます。

Amazon Bedrockのイベントストリーム応答では、明示的にオプトインしない限りバイト単位の監視が動きません。CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1で有効にします。

v2.1.242より前は、応答ヘッダーが来ない場合でもAPI_TIMEOUT_MSの10分いっぱいまで待ってから失敗していました。最初のバイトの期限が動く接続では、現在はヘッダーが期限までに来ないと途中で中断し、同じリクエストを1回だけ再送します。再送も応答がなければ、ターンが終わります。表示はAPI Error: No response from API (waited 3m, then 10m on the retry)のように、それぞれの待ち時間つきです。

それ以外の接続では、従来どおりAPI_TIMEOUT_MSまで待ちます。待ち時間つきの表示になったのはv2.1.261からで、Bedrockでは再送も初回と同じ期限になり、表示の待ち時間は1つだけです。

この再送は、期限の算定と待ち時間が初回と別になっています。Bedrock以外では、再送の待ち時間はAPI_TIMEOUT_MSより1秒短い値で、10分の既定なら10分弱です。プロキシやゲートウェイが応答を完了まで保留する環境でも、再送なら間に合うようにするための設計です。

API_TIMEOUT_MSが11秒未満の正の値だと、最初のバイトの期限そのものが無効になります。秒数の調整手順はClaude Codeの応答が止まったときのタイムアウト調整方法にまとめています。

サブエージェントがタイムアウトに巻き込まれたとき

Claude Code Sub-agents完全ガイドで扱うサブエージェントでは、APIエラーの出方が少し違います。フォアグラウンドのサブエージェントは、レート制限・overloaded・サーバーエラーで途中打ち切りになったとき、すでにテキスト出力があればその部分出力が親に返ります。このとき、打ち切られて完了していない旨の注記が付きます。

何も出力がなかったか、出力がツール呼び出しだけだった場合はAgent terminated early due to an API errorで失敗します。同じ失敗でも、手元に何が残るかは出力の形で決まります。

症状別の切り分け

次のように、症状ごとに触る場所が変わります。

• 毎回、20秒の待機表示が出る: 単発の遅延ではなく、ネットワーク側を疑う目安です。回線・VPN・プロキシを順に外して比べます
• 証明書まわりのエラーがすぐ出る: リトライされないので、NODE_EXTRA_CA_CERTSなどの証明書設定を直します
• No response from APIで止まる: プロキシやゲートウェイが応答を完了まで保留していないかを確認します。保留しているならAPI_TIMEOUT_MSを引き上げます。Amazon Bedrockでは、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSも上げる対処があります
• 初回だけ失敗して再送で通る: CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MSを上げて、初回の待ち時間を延ばす選択肢があります
• 長い生成の最中に落ちる: 指示を小さく分割し、1回のリクエストが長引きにくい形にします

リクエストのやり直しは、Claude Codeが自動でもやっていますが、手動でtry againと送り直しても構いません。

よくある質問

プロキシを使っていないのに頻発します

社内ネットワークの混雑や、一時的なAPI側の高負荷が原因のことがあります。数分空けて再試行しても改善しないなら、status.claude.comでインシデントの有無を確認してください。

タイムアウト値を極端に長くしても問題ないですか

API_TIMEOUT_MSを長くすれば、遅い応答は待てるようになります。代わりに、本当に応答不能な接続を検知するまでの時間も延びます。CI等で早期に失敗を検知したいなら、短めの値と低いCLAUDE_CODE_MAX_RETRIESの組み合わせが向いています。

CI環境で無人実行しているときはどう備えればよいですか

対話の入力待ちが無い実行では、リトライを使い切った時点でランが終わります。長い障害を待ち抜きたいジョブなら、CLAUDE_CODE_RETRY_WATCHDOG=1で429・529を無制限にリトライさせる選択肢があります。他の一過性エラーの既定回数も300回に上がり、公式の説明では約3時間分のバックオフに相当します。

逆に、失敗を早く知りたいテスト用途では、このスイッチを入れずCLAUDE_CODE_MAX_RETRIESを下げます。どちらを選ぶかは、ジョブが何分まで待てるかで決まります。支出上限を伝える429は、ウォッチドッグを有効にしても待たずに失敗するため、そこは別の手当てが要ります。

設定を変えたのに効いていないように見えます

先に確認したいのは、変数がclaudeのプロセスに渡っているかどうかです。exportは設定した端末でしか有効にならず、別の端末やIDEから起動したセッションには届きません。echo $API_TIMEOUT_MSで値が出るかを同じ端末で確かめると、設定の問題か、タイムアウト以外の原因かを切り分けられます。

まとめ

切り分けは、まず画面の文言を読むところから始まります。待機表示なのか、応答前の時間切れなのか、途中切断なのかで、触る設定が決まります。