Claude Code の API エラー対処:自動リトライと使用量上限

Claude Code 入門 7分で読めます

Claude Code を使っていると、API Error: 500、Repeated 529 Overloaded errors、Request timed out、You've hit your session limit といったメッセージに出会うことがあります。多くは一時的なもので Claude Code が自動で再試行していますが、自分の設定や認証情報が原因のものは手で直す必要があります。この記事では、公式ドキュメント「Error reference」をもとに、自動リトライのしくみ、リトライとタイムアウトを調整する環境変数、サーバーエラー・途中切断・認証・使用量上限の各エラーの意味と対処を整理します。インストールやログインの段階で出るエラーはインストールとログインのトラブル対処の記事を参照してください。

自動リトライのしくみ

公式ドキュメントによると、ここで扱う実行時のエラーは CLI・デスクトップアプリ・クラウドのセッションで共通です。また、ほとんどのエラーはその下にある API のエラーコードに対応しており、HTTP ステータスそのものの定義は Claude Platform 側のエラーリファレンスにまとまっています(API を直接呼ぶ場合はClaude API のエラーの記事も参照)。

Claude Code は一時的な失敗を最大10回、指数バックオフで自動的に再試行します。再試行の対象と対象外は次のとおりです。

自動で再試行するもの再試行しないもの
応答がまだ流れ始める前に起きたサーバーエラー・過負荷・タイムアウト/応答が出る前に接続が切れた・止まった場合TLS 証明書の失敗/Claude がテキストやツール呼び出しを出し終えた後の途中失敗/応答が完了した後の失敗

再試行中はスピナーに Retrying in Ns · attempt x/y のように待ち時間と試行回数が表示されます。また、データが届かない状態が20秒以上続くと「API の応答待ち」であることを示す表示が出ます(ゲートウェイ経由の場合、v2.1.309 以降は45秒)。画面にエラーが出るのは、こうした再試行を使い切った後か、そもそも再試行の対象外だった場合です。

リトライを調整する環境変数

再試行の回数や待ち時間は環境変数で調整できます。公式のエラーリファレンスに載っている主なものは次のとおりです(バージョン条件のあるものは、claude --version で手元のバージョンを確かめてから使います)。

変数既定値働き
CLAUDE_CODE_MAX_RETRIES10再試行の回数。v2.1.186 以降は上限15
CLAUDE_CODE_RETRY_WATCHDOG未設定1 にすると、無人のセッションで 429 と 529 を無期限に再試行する
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS未設定ウォッチドッグ有効時の 429/529 の待ち時間の上限(v2.1.295 以降)
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS500529 再試行の最初の待ち時間(v2.1.292 以降)
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS32000529 再試行の待ち時間の上限(v2.1.296 以降)
API_TIMEOUT_MS600000各試行が応答ヘッダーを受け取るまでの時間(ミリ秒)
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS未設定ストリーミング要求の最初のバイトまでの期限(v2.1.242 以降)

環境変数リファレンスでは、API_TIMEOUT_MS は「応答ヘッダーを受け取るまで」の制限で、ストリーミングが始まった後の長さは制限しないと説明されています。遅い回線やプロキシ経由でタイムアウトする場合に値を増やし、0 にすると制限を外せます(v2.1.305 以降。その場合でも非ストリーミングの試行はローカルでは300秒で打ち切られます)。また CLAUDE_CODE_MAX_RETRIES については、529 では設定回数より早く止まることがあり、フォールバックモデルを設定していればエラーを出す代わりにそのモデルへ切り替わる、と補足されています。長い障害を待ち続けたい無人の実行では、回数を増やすより CLAUDE_CODE_RETRY_WATCHDOG を使うよう案内されています。

# 例: プロキシ経由で応答ヘッダーが遅い環境で待ち時間を20分にする
export API_TIMEOUT_MS=1200000
claude

サーバーエラーとタイムアウト

再試行を使い切っても解決しなかったときに出る代表的なメッセージです。

社内プロキシや独自の CA を使う環境で接続そのものができない場合は、プロキシ・社内CA・mTLS の設定も確認してください。

応答が途中で切れたとき

Claude が応答を書いている最中に失敗すると、それまでの出力は残ったまま、次のようなメッセージが表示されます。いずれも末尾に「The response above may be incomplete.(上の応答は不完全な可能性がある)」と付きます。

メッセージ起きたこと
API Error: Server error mid-response.応答の途中で過負荷や 5xx のエラーが起きた
API Error: Connection lost mid-response.接続が切れた
API Error: Your computer went to sleep mid-response.受信中にマシンがスリープした
API Error: The response stopped arriving.止まったストリームをアイドル監視が打ち切った

前述のとおり、Claude がテキストやツール呼び出しを出し終えた後の失敗は自動では再試行されません。対処はどれも同じで、途中までの出力を読んでから、対話セッションで continue と返信します。-p(ヘッドレスモード)で実行していた場合は、セッションを再開して continue を送ります。Amazon Bedrock で、最初の試行がタイムアウトして再試行では成功するという状態が続く場合は、CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS を増やすよう案内されています。

認証と使用量上限のエラー

認証のエラーは、今どの認証情報が使われているかを /status で確かめるのが出発点です。意図しない ANTHROPIC_API_KEY が残っていてログインより優先されている、というのがよくある原因です。

表示対処
Not logged in · Please run /login/login を実行する。環境変数で認証するつもりなら、起動したシェルで ANTHROPIC_API_KEY が export されているか確認する。CI では apiKeyHelper スクリプトを設定する
Invalid API key · Fix external API keyキーの打ち間違いや失効を Console で確認する。env | grep ANTHROPIC(PowerShell は Get-ChildItem Env:ANTHROPIC*)で設定を見て、unset ANTHROPIC_API_KEY の後に /login
Your apiKeyHelper script is failingヘルパーを直接実行して確かめる。標準出力にはキーだけを出し、終了コード0で終わるようにする。ヘルパーが設定されている間は /login では直らない
OAuth token revoked / Login expired/login を実行する。CLAUDE_CODE_OAUTH_TOKEN を設定している場合は claude setup-token で新しいトークンを作るか、変数を外して /login
API Error: 401 Invalid authentication credentials/status で確認し、API キーが有効ならローテーションするか外す。ログインだけなら /login。同じログインで失敗し続けるなら管理者にアクセスの復旧を依頼する

使用量の上限に達した場合は、次のようなメッセージになります。

利用状況やコストの把握についてはコストを効果的に管理するの記事が参考になります。

本記事は Claude Code 公式ドキュメント「Error reference」を元に、同じく公式の Environment variables で API_TIMEOUT_MS・CLAUDE_CODE_MAX_RETRIES・CLAUDE_CODE_DISABLE_1M_CONTEXT の説明を照合した非公式の日本語解説です(確認日 2026-11-18)。エラー文や既定値、必要なバージョンは更新される可能性があるため、利用前に公式ドキュメントをご確認ください。