Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

利用上限とは無関係な、一時的なサーバー側のレート制限エラー（429）は、ターンを失敗させるのではなく、サブスクライバー向けにバックオフ付きで自動的にリトライされるようになりました。

原文（英語） ​

Transient server rate-limit errors (429s unrelated to your usage limit) are now retried automatically with backoff for subscribers instead of failing the turn

概要 ​

Claude Codeは Server is temporarily limiting requests (not your usage limit) という一時的なレート制限エラーを、プランの利用上限（セッション/週次の使用量制限）とは別物として扱います。これは、実際の利用上限超過時に付与される専用のクォータヘッダーが無いことで区別されます。v2.1.199より前は、claude.ai サブスクリプションでサインインしているセッションはこのエラーが発生した時点で即座にターンを失敗させていましたが（APIキー・Enterprise認証のみリトライ対象でした）、v2.1.199からは認証方法によらず、このエラーも指数バックオフで自動リトライされてからでないとユーザーに表示されなくなりました。

基本的な使い方 ​

特別な設定は不要です。通常どおりClaude Codeを使っていれば、一時的なレート制限エラーが発生した際に自動的にリトライが行われます。

text
Retrying in 3s · attempt 2/10

このようなカウントダウン表示が出ている間は、Claude Codeが裏側で自動リトライを行っている状態です。リトライがすべて尽きた場合にのみ、エラーメッセージが表示されます。

実践例 ​

サブスクリプションでサインインしたセッションでの挙動を確認する ​

claude.ai のPro/Max/Teamプランなどでサインインしている場合、以前は一時的なレート制限に当たるとその場でターンが失敗していましたが、v2.1.199以降はAPIキー認証と同様にバックオフ付きで自動リトライされ、リトライが尽きるまでエラーは表示されません。

/status で現在の認証方式を確認する ​

意図せず環境変数にAPIキーが残っていると、サブスクリプションではなく低いレート制限のキー経由でリクエストが送られることがあります。

bash
claude
> /status

/status で有効な認証情報がサブスクリプションになっているか確認しておくと、想定外のレート制限エラーの切り分けがしやすくなります。

リトライ回数を調整する ​

デフォルトのリトライ回数（10回、上限15回）を調整したい場合は CLAUDE_CODE_MAX_RETRIES を設定します。無人実行（CIなど）でさらに粘り強くリトライさせたい場合は CLAUDE_CODE_RETRY_WATCHDOG の利用も検討してください（詳細は関連記事を参照）。

bash
export CLAUDE_CODE_MAX_RETRIES=5

注意点 ​

  • このエラーは、プランの利用上限（You've hit your session limit / You've hit your weekly limit）とは別物です。利用上限の場合はリトライしても解消しません。
  • リトライの試行回数は CLAUDE_CODE_MAX_RETRIES（デフォルト10回、通常は15回が上限）に従います。
  • 頻発する場合は status.claude.com でサービス状況を確認してください。
  • スクリプトなど失敗を即座に検知したい用途では、CLAUDE_CODE_MAX_RETRIES を低い値に設定するとリトライを待たずに早期に失敗させられます。

関連情報 ​