Claude Code Request timed outエラー — 原因と対処法
Claude Codeで「Request timed out」が出たときの原因切り分けと対処。429・overloadedとの違い、自動リトライの範囲、API_TIMEOUT_MSの調整方法をまとめます。
Claude CodeでRequest timed outと表示されるのは、APIへのリクエストが接続デッドラインまでに応答を返さなかったサインです。デフォルトのリクエストタイムアウトは10分。高負荷時や、モデルが非常に長い応答を生成している最中に起きます。
Request timed outとは何か
Request timed outは、Claude CodeがAPIへ送ったリクエストへの応答が届かないまま、設定されたタイムアウト値を超えたときに出るエラーです。既定値は600,000ミリ秒、つまり10分です。
Request timed outこのエラーはネットワーク断とは別物です。接続自体は成立しているものの、応答が時間内に返ってこない状態を指します。回線が実際に切れている場合は、メッセージに「your internet connection」への言及が付き、扱いが変わります。
429・overloadedとは何が違うか
似た場面で出るエラーに429(レート制限)と529 Overloadedがあります。3つは原因も対処もそれぞれ異なります。
| エラー | 意味 | あなたの上限との関係 |
|---|---|---|
| Request timed out | 意味応答がタイムアウト値を超えて届かない | あなたの上限との関係上限とは無関係。ネットワークや応答生成の遅さが原因 |
| 429 | 意味レート制限に到達 | あなたの上限との関係プランやAPIキーの使用量上限に関係する |
| 529 Overloaded | 意味API全体が容量不足 | あなたの上限との関係上限消費にはカウントされない |
429とoverloadedの詳しい切り分けと回復手順はClaude rate limitエラーの対処にまとめています。Request timed outは、この2つとは別軸の「時間切れ」の問題です。
CLI・デスクトップ・Web、どこで見ても同じ意味か
Request timed outを含むこのページのエラーメッセージは、ターミナルのCLIだけでなくDesktopアプリやClaude Code on the webでも共通です。3つとも内部では同じClaude Code CLIをラップしているため、表示されるメッセージも復旧手順も基本的に変わりません。VS Code拡張やJetBrainsプラグインが独自に出す起動時エラーのような、ラッパー側固有の表示だけは例外です。つまり、どの利用形態でRequest timed outを見ても、ここで説明する原因の切り分けと対処がそのまま当てはまります。
Claude Codeが自動でリトライする範囲
Claude Codeは一過性の失敗を最大10回、指数バックオフで自動リトライしてから、それでも解決しなければエラーを表示します。応答がまだ何も届いていない段階でのタイムアウトはリトライ対象です。サーバーエラー・overloadedな応答・応答開始前のタイムアウトが該当します。
応答ストリームに20秒間データが来ないと、リトライが始まる前にWaiting for API response · will retry in … · check your networkという表示が出ます。これはまだ失敗が確定した状態ではなく、接続を切って再試行するまでのカウントダウンです。データが再開するか、リトライが成功すれば表示は自然に消えます。毎回この表示が出るなら、単発の遅延ではなくネットワーク側の問題として扱うのが適切です。
一方で、Claudeの応答がすでに一部でも届き始めたあとに途切れた場合は扱いが変わります。「Response incomplete」の通知という別のメッセージになります。Request timed outが指すのは、あくまで応答が始まる前の段階での時間切れであり、両者は原因も見分け方も別物です。
大事なのは、目の前に表示されたRequest timed outは「最初の失敗」ではなく「リトライを使い切った末の結果」だという点です。裏側では最大10回のバックオフがすでに走っているため、この表示が出た時点でもう一度手動で連投しても、直後にまた同じ失敗になる可能性があります。数十秒から数分空けてから再試行したほうが解消しやすい場面が多いです。
リトライされない失敗との違い
Request timed outを含む一過性の失敗は自動リトライの対象ですが、Claude Codeがまったくリトライしない失敗もあります。代表例がTLS証明書の検証エラーです。社内プロキシによる証明書の差し替えや、NODE_EXTRA_CA_CERTSの未設定、証明書の期限切れが原因のときは、Claude Codeはリトライせず最初の試行で即座にエラーを返します。設定を直さない限りリトライしても無駄だからです。Request timed outが繰り返し出るのにこの即時失敗のパターンが見られない場合は、証明書ではなく純粋な応答遅延が原因と判断できます。同様に、応答がすでに一部完了したあとに接続が切れた場合も、二重実行を避けるためにリトライではなく「途中経過を保持したまま終了」という別の扱いになります。
何をすればよいか
- リクエストをやり直す(Claude Codeは自動でも再試行しますが、手動で
try againと送り直しても構いません) - 長時間タスクは小さいプロンプトに分割する
- 遅い回線やプロキシ経由の場合は
API_TIMEOUT_MSを引き上げる - 頻発し、ネットワーク自体は健全に見えるなら「ネットワークと接続のエラー」の切り分けに進む
社内プロキシや証明書経由でClaude Codeを使っている場合、タイムアウトの体感頻度が上がりやすい環境です。プロキシ設定の要点はClaude Codeプロキシ設定で扱っています。
API_TIMEOUT_MSで調整する
タイムアウト自体の長さは環境変数で変更できます。
export API_TIMEOUT_MS=1200000| 変数 | 既定値 | 効果 |
|---|---|---|
API_TIMEOUT_MS | 既定値600000(10分) | 効果リクエスト1本あたりのタイムアウト。遅い回線・プロキシで引き上げる |
CLAUDE_CODE_MAX_RETRIES | 既定値10 | 効果リトライ回数の上限。CI等で失敗を早く表面化させたいなら下げる |
CLAUDE_CODE_RETRY_WATCHDOG | 既定値未設定 | 効果1を設定すると429・529を無制限にリトライし続け、他の一過性エラーの上限も300回に引き上がる |
CLAUDE_CODE_RETRY_WATCHDOGはCIジョブや常駐運用のような無人セッション向けです。対話セッションで安易に有効化すると、詰まったリクエストに長時間張り付いたまま気づきにくくなります。環境変数の全体像はClaude Code環境変数リファレンスで確認できます。
ストリーミング応答が固まっているように見えるとき
Claude Codeは応答ストリームの生存確認に3種類の独立したタイマー(watchdog)を使っています。バイト単位で監視するもの、パース済みイベント単位で監視するもの、5分間データが来なければ切るボディアイドルタイムアウトです。既定の秒数はAPI経路によって180秒〜300秒と幅があり、Amazon Bedrockのイベントストリーム応答では明示的にオプトインしない限り一部のwatchdogが動きません。表示上は同じ「応答が来ない」に見えても、内部で監視している層が違う点は、原因切り分けの手がかりになります。バイト単位のwatchdogは、SSEのkeep-aliveピングのようなごく小さなデータでもタイマーをリセットするため、本当に何も流れていない接続を優先して検知します。
サブエージェントがタイムアウトに巻き込まれたとき
Sub-agentsに委譲したタスクの中でAPIエラーが解消しないままリトライが尽きると、Agent terminated early due to an API errorという別のメッセージで終了します。委譲先のタスク設計やレジューム方法はClaude Code Sub-agents完全ガイドにまとめています。
よくある質問
Request timed outは使用量の上限消費に含まれますか
含まれません。429や週次上限のようなプラン消費とは無関係で、応答が時間内に届かなかったという通信上の事象です。
プロキシを使っていないのに頻発します
社内ネットワークの混雑や、一時的なAPI側の高負荷が原因のことがあります。数分空けて再試行しても改善しないなら、status.claude.comでインシデントの有無を確認してください。
タイムアウト値を極端に長くしても問題ないですか
API_TIMEOUT_MSを長くする分には動作上の問題はありませんが、実際に応答不能な接続を検知するまでの時間も延びます。CI等で早期に失敗を検知したい場合は、逆に短めの値と低いCLAUDE_CODE_MAX_RETRIESの組み合わせが向いています。
VS CodeやDesktopアプリでも同じ対処でよいですか
はい。表示されるメッセージも自動リトライの仕組みも共通なので、ここで説明した内容がそのまま当てはまります。環境変数を設定する場所だけ、ターミナルから起動する場合とDesktopアプリの設定から起動する場合とで異なります。
大きなワークフローを並列実行しているときだけ頻発します
同時に複数のリクエストを送るワークフローは、単発の対話より高負荷時のタイムアウトに当たりやすくなります。並列度を落とすか、タスクを小さい単位に分割してリクエスト1本あたりの処理時間を短くすると発生頻度を抑えられます。
CI環境で無人実行しているときはどう備えればよいですか
対話プロンプトが無い非対話実行では、失敗した時点でリトライが尽きるとそのままランが終了します。CIジョブのように長時間放置する用途ではCLAUDE_CODE_RETRY_WATCHDOG=1を設定しておくと安心です。429・529・一過性エラーをより粘り強くリトライし続け、単発のタイムアウトでジョブ全体が落ちる事態を避けやすくなります。逆に失敗を早く検知したいテスト用途では、既定のリトライ回数のままAPI_TIMEOUT_MSだけを短めに調整するほうが向いています。
まとめ
Request timed outは応答が時間内に届かない通信上の事象で、レート制限や容量不足とは原因がまったく別です。多くはClaude Codeの自動リトライだけで解消し、頻発する場合だけAPI_TIMEOUT_MSの調整やプロキシ環境の見直しに進めば十分です。あわてて設定を変える前に、まずは数分空けての再試行を試してください。