Claude Code ガイド

Appearance

429エラーリトライ時のバックオフ修正：短いRetry-Afterでリトライが消費されていた問題 ​

原文（日本語に翻訳） ​

サーバーが短いRetry-After値を返した場合に、約13秒でリトライ試行がすべて消費されていた429エラーのリトライ問題を修正しました。エクスポネンシャルバックオフが最小値として適用されるようになりました。

原文（英語） ​

Fixed 429 retries burning all attempts in ~13s when the server returns a small Retry-After — exponential backoff now applies as a minimum

概要 ​

HTTPステータスコード429（Too Many Requests）はレート制限を示し、サーバーはRetry-Afterヘッダーで次のリトライまでの待機時間を指定します。このバグでは、サーバーが非常に短いRetry-After値（例：1秒）を返した場合、Claude Codeが設定されたリトライ回数をわずか約13秒で使い切ってしまい、その後のリクエストがすべて失敗していました。v2.1.98でエクスポネンシャルバックオフが最小値として適用されるようになり、リトライが適切な間隔で行われるようになりました。

基本的な使い方 ​

修正前の動作（問題のある挙動） ​

# 修正前の動作例
$ claude "大量のコードを処理してください"
[リクエスト1] → 429 Too Many Requests (Retry-After: 1s)
[1秒後リトライ] → 429 Too Many Requests (Retry-After: 1s)
[1秒後リトライ] → 429 Too Many Requests (Retry-After: 1s)
... (約13秒でリトライ回数を使い切る)
Error: Rate limit exceeded, max retries reached
# リトライ間隔が短すぎて、全リトライが約13秒以内に消費されていた

修正後の動作（v2.1.98以降） ​

# 修正後の動作例
$ claude "大量のコードを処理してください"
[リクエスト1] → 429 Too Many Requests (Retry-After: 1s)
[最低バックオフ時間後リトライ] → 429 Too Many Requests
[エクスポネンシャルバックオフ: 2s, 4s, 8s...]
[十分な待機後] → 200 OK（処理成功）
# エクスポネンシャルバックオフにより適切な間隔でリトライが行われる

実践例 ​

シナリオ1：高負荷時のAPI使用（修正後） ​

大量のリクエストを処理するバッチ処理でレート制限に達した場合の動作が改善されます。

bash
# 複数ファイルを順次処理するスクリプト
for file in src/**/*.py; do
    claude "このファイルのドキュメントを生成してください" < "$file"
    # レート制限が発生してもエクスポネンシャルバックオフで適切にリトライ
done

シナリオ2：CIパイプラインでのレート制限対応（修正後） ​

CIパイプラインでClaude Codeを使用する際、レート制限に達してもパイプラインが継続されます。

yaml
# GitHub Actions での例
- name: Code Review with Claude
  run: |
    claude "変更されたファイルをレビューしてください" < changes.diff
    # 429エラーが発生しても、エクスポネンシャルバックオフで自動リトライ
    # 修正前と異なり、短時間でリトライを使い切ることがなくなった

シナリオ3：企業環境でのAPIクォータ管理（修正後） ​

組織でAPIのクォータが設定されている場合、より効率的にリトライが行われます。

bash
# チーム共有のAPI キーを使用する場合
# レート制限が厳しい時間帯でも、適切なバックオフにより最終的にリクエストが成功

claude --model claude-opus-4-5 "詳細な分析を行ってください" < large_data.txt
# サーバーの Retry-After: 1 のような短い値でも
# エクスポネンシャルバックオフ（最低値）が適用される

シナリオ4：バックオフの動作確認（修正後の詳細） ​

エクスポネンシャルバックオフの最小値が適用される仕組み：

Retry-After: 1s の場合（修正後）:
- リトライ1: max(1s, 2^0 * base_delay) = 適切な最小バックオフ時間を待機
- リトライ2: max(1s, 2^1 * base_delay) = 指数的に増加した待機時間
- リトライ3: max(1s, 2^2 * base_delay) = さらに長い待機時間
- ...
→ 合計待機時間が適切に確保され、リトライが無駄に消費されない

修正前:
- リトライ1: 1s待機 → リトライ
- リトライ2: 1s待機 → リトライ
- リトライ3: 1s待機 → リトライ
... (短時間で全リトライ消費)

注意点 ​

  • この修正はAPI のレート制限（429エラー）が発生した場合の動作改善です。レート制限を受けないよう、APIの使用量を適切に管理することも重要です。
  • エクスポネンシャルバックオフにより、リトライ間隔が徐々に長くなります。緊急性の高い処理では、レート制限を受けないようAPIの使用計画を立てることを推奨します。
  • 組織でClaude Codeを多数のユーザーが使用している場合、APIクォータの管理とモニタリングを強化することを検討してください。
  • この修正はRetry-Afterヘッダーを返すサーバーへのリクエストに対して効果があります。Retry-Afterヘッダーがない場合は、通常のエクスポネンシャルバックオフが適用されます。

関連情報 ​