Anthropic 529 overloaded_error: その意味と処理方法

Claude API は、API が一時的にオーバーロードされたときに、エラーの種類529でoverloaded_errorを返します。 Anthropicによると、API が全ユーザーにわたって高トラフィック状態になると発生する可能性があります。要求は問題ありません。 API がビジー状態であるため、リクエストを拒否しました。組織が独自のレート制限を超えると、代わりに 429 エラーが返されます。応答本文は、他のすべてのClaude APIエラーと同じ構造です。つまり、最上位にtypeのerrorがあり、messageとerrorを持つtypeオブジェクトと、Anthropicサポートに提供できるrequest_idがあります。詳細については、「 Claude API エラー」を参照してください。

529、429、または支出上限: それらを区別する方法

Claude API では、見た目が似ているエラーが、まったく異なる問題に対して使われます。しばらく待つと消えるものもあります。それは来月まで消えません。

応答	`error.type`	`retry-after`	意味	何をすべきか
`529`	`overloaded_error`	それがあれば使用します	API は、すべてのユーザーに対して過負荷状態です	バックオフして数回再試行する
`429`	`rate_limit_error`	Yes	組織は、要求数の上限、入力トークン、または 1 分あたりの出力トークンの上限を超えたか、急激に増やしすぎて加速制限に達しました	`retry-after` と表示されるまで待ちます
`429`	`rate_limit_error`、`error.details.error_code` が `enforced_spend_limit_reached` に設定されている	No	組織が利用階層の月間支出上限に達しました	再試行しないでください。使用量は、翌月の最初の日の 00:00 UTC まで、または上位レベルに移行するまで一時停止します。
`400`	`invalid_request_error`	No	組織またはワークスペースで設定した支出上限に使用量が達しました	制限を上げるまたは削除する

支出上限による 429 エラーの種類はレート制限と同じであるため、rate_limit_error ごとに再試行するコードは失敗し続けます。 Anthropic は、SDK の自動再試行を含め、アクセスが再開されるまで再試行は失敗すると述べています。詳細については、「支出上限に達した場合」を参照してください。

529 に対処する方法

再試行する前に、状態コードを確認してください。 529と429には異なる待機が必要であり、429のないretry-afterはまったく再試行する必要はありません。
529はやめておく。 指数バックオフとランダムジッターを使用して再試行し、数回試行した後に停止します。応答に retry-after ヘッダーがある場合は、代わりにその時間だけ待ちます。
最初の再試行はSDKに任せます。 公式Anthropic SDK では、接続エラー、レート制限、5xx エラーに対して、指数バックオフを使用して既定で 2 回再試行を行い、存在する場合はretry-afterに従います。 max_retries (TypeScript ではmaxRetries) でカウントを変更できます。 SDK の再試行回数が不足すると、コードはエラーを受け取ります。
支出上限に達した場合の再試行を停止します。 429 に retry-after ヘッダーがない場合は、ユーザーに通知し、自分にも警告します。
ユーザーに情報を提供します。 作業をキューに入れて後でもう一度やり直すか、一般的なエラーではなく、明確な「ビジー状態です。1 分後に再試行してください」というメッセージを表示する。

Python SDK では、429 によってanthropic.RateLimitErrorが発生し、529 を含む 500 以上のステータスコードでは、anthropic.InternalServerErrorが発生します。

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

アプリが 529 を処理することをテストする方法

開発中に 529 が表示されることはほとんどありません。これはすべての Claude API ユーザーからのトラフィックに依存するため、トリガーすることはできません。どのようにテストするかによって、ユーザーより先にバグを見つけられるかどうかが左右されます。

Approach	見つけたもの	見逃したもの
本番環境を待機	真のオーバーロード	ユーザーがアクセスするまでは、すべて
テストで API をモックするか、コーディングエージェントにモックを記述させる	エラーブランチが実行されるかどうか	Anthropicの実際の状態コードとエラー本文、および SDK の再試行ポリシー。アプリでは、モックに到達するためにテスト専用のスイッチも必要です。
失敗するまで実際の API を呼び出す	実際の動作	オンデマンドで 529 を発生させることはできません。また、支出上限に安全に到達させることもまったくできません。
お使いのアプリの実際の通信をインターセプトし、529 と 429 をオンデマンドで返す	実際の URL、実際の SDK と再試行ポリシー、Anthropic独自のエラー形式	アプリ内では何も変更されないため、コードを独立した状態でテストするわけではありません。そのための単体テストは取っておいてください。

アプリで試す

Dev Proxyは、アプリのhttps://api.anthropic.comへの要求をインターセプトし、Anthropicのエラー形式でエラーを返しますが、アプリは実際のURLを呼び出し続けます。プリセットをダウンロードし、そのプリセットで Dev Proxy を起動します。

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Preset	それが返すもの
`anthropic-throttling`	4,429 件のレスポンスのうち、ランダムに 1 件 `rate_limit_error`（リクエスト、入力トークン、出力トークン、レート制限）または 529 `overloaded_error`。 429s では、開発プロキシは `retry-after` を設定し、アプリが API を呼び出すのが早すぎるときに通知します。
`anthropic-random-errors`	リクエストの50%について、400、401、402、403、404、409、413、429、500、504、529 を含む Claude API のエラー一覧から、ランダムに1つのエラー

どちらのプリセットにも支出上限 429 は含まれていません。そのパスをテストするには、retry-after ヘッダーを含まないレスポンスをプリセットの anthropic-errors.json ファイルに追加してください。

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

すべての要求が失敗し、SDK の再試行回数を使い果たしたときに何が起こるかを確認するには、--failure-rate 100を使用して Dev Proxy を起動します。詳細については、「変更リクエスト失敗率」を参照してください。 Dev Proxy をインストールするには、「Dev Proxy のセットアップ」を参照してください。

次のステップ

ランダムエラーでアプリをテストする

参照

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-10-05