Claude APIを本番で使っていると、ある日突然529 overloaded_errorが返ってきて処理が止まった経験はありませんか。特にリリース直後やキャンペーン中などアクセスが集中するタイミングで発生しやすく、原因も対処法も分かりにくいエラーです。本記事ではClaude API 529 overloaded_errorが起きる原因を整理し、Pythonの公式SDKを使った再試行（リトライ）・指数バックオフの実装コードを紹介します。

Claude API 529 overloaded_errorとは何か

Anthropic APIがエラー時に返すステータスコードとエラータイプは、HTTPステータスとレスポンスボディのerror.typeで判別できます。529は「Anthropic側のサーバーが一時的に過負荷状態にある」ことを示すコードで、リクエスト内容や自分のAPIキーの利用量には関係なく発生します。

429・500・503との違い

ステータス

error.type

原因

自分側で制御可能か

429

rate_limit_error

自分のアカウントのレート制限超過（RPM/TPM/ITPM等）

可能（送信頻度・トークン量を調整）

500

api_error

Anthropic側の予期しない内部エラー

不可

503

overloaded_error

Anthropic側の一時的な過負荷（旧バージョンで使用されることがある）

不可

529

overloaded_error

Anthropic側の一時的な過負荷（現行の主要コード）

不可

429は「自分のリクエストが多すぎる」ことが原因なのに対し、529は「Anthropicのインフラ全体が混雑している」ことが原因です。つまり自分のコードやリクエスト内容を直しても529自体は防げません。できるのは、発生したときに落ちずに再試行できる仕組みを作ることだけです。

529が起きたときにやってはいけない実装

よくある失敗パターンは次の2つです。

  • 即座に1回だけリトライして諦める：過負荷状態は数秒〜数十秒続くことが多く、間隔を空けずに再送してもまた529になりやすい
  • リトライ間隔を固定秒数にする：全クライアントが同じタイミングで再送すると、Anthropic側の負荷が下がりきる前に再び集中し、過負荷が長引く原因になる

この2つを避け、指数バックオフ（リトライごとに待機時間を倍々に伸ばす）＋ジッター（ランダムなゆらぎ）を組み合わせるのが定石です。

Python SDKでの再試行・指数バックオフ実装コード

公式SDKの組み込みリトライを使う（最も簡単）

Anthropic公式のPython SDK（anthropicパッケージ）は、429・500・503・529などのエラーやコネクションエラーに対してデフォルトで自動リトライする仕組みを内蔵しています。デフォルトの最大リトライ回数は2回ですが、max_retriesで調整できます。

import anthropic

# クライアント生成時にリトライ回数を指定するだけで、
# 529・500・503・429・接続エラー時に自動で指数バックオフ再試行される
client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    max_retries=5,   # デフォルトは2。過負荷が読めない場合は多めに
    timeout=60.0,
)

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
)
print(response.content[0].text)

まずはこのmax_retriesを適切な値に設定するだけで、529の大半は自動的に吸収されます。個別のリクエストだけリトライ回数を変えたい場合は、with_options()で上書きも可能です。

response = client.with_options(max_retries=8).messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
)

自前で指数バックオフを実装する（SDKのリトライで足りない場合）

バッチ処理などで「SDKの組み込みリトライを超えて、さらに長時間粘り強く再試行したい」場合や、リトライのたびにログを残したい場合は、自前でラップする実装が有効です。

import time
import random
import anthropic

def call_claude_with_backoff(client, max_attempts=6, base_delay=1.0, **kwargs):
    """529等のエラー時に指数バックオフ+ジッターで再試行する"""
    for attempt in range(1, max_attempts + 1):
        try:
            return client.messages.create(**kwargs)
        except anthropic.APIStatusError as e:
            # 529(overloaded_error) / 500 / 503 / 429 のみ再試行対象とする
            retryable = e.status_code in (429, 500, 503, 529)
            if not retryable or attempt == max_attempts:
                raise

            # retry-afterヘッダーがあれば優先、なければ指数バックオフ+ジッター
            retry_after = e.response.headers.get("retry-after")
            if retry_after:
                delay = float(retry_after)
            else:
                delay = base_delay * (2 ** (attempt - 1))
                delay += random.uniform(0, delay * 0.3)  # ジッター

            print(f"[attempt {attempt}] status={e.status_code} "
                  f"{delay:.1f}秒後に再試行します")
            time.sleep(delay)

    raise RuntimeError("リトライ上限に達しました")


client = anthropic.Anthropic(api_key="YOUR_API_KEY", max_retries=0)  # 自前実装と二重にならないよう0に

response = call_claude_with_backoff(
    client,
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
)
print(response.content[0].text)

ポイントは3つです。

  1. 再試行対象を429/500/503/529に限定する：400（不正なリクエスト）や401（認証エラー）はリトライしても解決しないため、即座にraiseして原因を潰す
  2. retry-afterヘッダーがあれば優先する：Anthropic側が推奨する待機秒数を返してくることがあるため、自前の指数計算より信頼できる
  3. SDKのmax_retriesと自前リトライを二重にしない：両方有効にすると待機時間が想定以上に伸びるため、自前実装を使う場合はSDK側をmax_retries=0にする

ストリーミング利用時とバッチ処理での注意点

ストリーミング（stream=True）は途中失敗に注意

ストリーミング中に529が発生した場合、SDKの自動リトライは接続確立前のエラーには効きますが、ストリーム開始後に切断された場合は再試行されません。ストリーム開始後の切断は例外をキャッチし、途中まで受信したテキストを破棄して最初からリクエストをやり直す設計にしておく必要があります。

大量リクエストのバッチ処理は同時実行数を絞る

複数リクエストを並列実行するバッチ処理では、同時実行数が多いほど529が連鎖的に発生しやすくなります。asyncio.Semaphoreなどで同時実行数の上限を設け、Anthropic側の負荷を無用に増やさないようにするのも有効な対策です。

それでも529が頻発する場合の切り分け

  • 特定モデルだけで発生する場合：新モデルのリリース直後は利用集中で過負荷になりやすいため、旧モデルへの一時フォールバックを検討する
  • 特定時間帯に集中する場合：米国時間の日中帯（日本時間深夜〜早朝）はトラフィックが多く529が出やすい傾向がある。バッチ処理の実行時間帯をずらすだけで改善することがある
  • Amazon Bedrock / Google Vertex AI経由の場合：Anthropic直接ではなく各クラウド側のスロットリングが原因のこともあるため、エラーメッセージの発生元を確認する

APIエラーへの再試行設計は、外部APIを利用するスクレイピングや自動化スクリプト全般で共通する考え方です。あわせてrequests 403 Forbidden対処【26年8月】やスクレイピング実装テクニック【2026年8月最新】も参考にしてください。

この記事に関連するアイテム

実際に使うものを選ぶ際の参考にどうぞ。

※ 本サイトはAmazonアソシエイト・プログラムの参加者です。紹介リンクを経由してご購入いただいた場合、手数料を受け取ることがあります。

まとめ

Claude APIの529 overloaded_errorはAnthropic側の一時的な過負荷が原因で、自分のリクエストを直しても防げません。対策は、公式SDKのmax_retries設定を適切に使うか、自前で指数バックオフ＋ジッターの再試行ロジックを実装することです。429・500・503のみを再試行対象とし、retry-afterヘッダーを優先する設計にすれば、本番運用でのエラー停止を大幅に減らせます。

業務自動化・スクレイピングの導入をご検討の方はnashiまでお問い合わせください。https://nashi-portfolio.netlify.app