AIものさし

Claude APIの529 overloaded_errorをレート制限と分けて復旧する

Claude APIの呼び出しでHTTP 529、overloaded_errorが返ったとき、429のrate limitやspend capと混同すると、調べる場所と再試行の仕方を誤ります。

AIものさし編集部

Claude APIの呼び出しでHTTP 529、overloaded_errorが返ったとき、429のrate limitやspend capと混同すると、調べる場所と再試行の仕方を誤ります。Anthropicの現行APIエラー資料では、529はAPIが一時的に過負荷になっている状態、429は組織のrate limit、利用tierのmonthly spend cap、またはClaude Code workspaceのspend limitに達した状態として別に説明されています。まずHTTP status、error.type、メッセージ、request IDを一組で確認し、529なら一時的な混雑の可能性、429なら利用制限や予算状態を調べるという分岐を作ります。

ここではAPI運用の診断手順を示します。特定アカウントの実リクエストや現在のAnthropic障害状況は確認していません。API状態や上限は変わるため、本文は固定的な復旧保証ではなく、公式エラー情報と実際の応答を起点に使ってください。

目次

最初に保存する応答情報

失敗を再現した時点で、status code、error.type、error.message、request-id、発生時刻、endpoint、model、処理形態（streamingか非streamingか）をログに残します。SDKを使う場合はSDKの例外クラスとraw response accessから取得できる情報も確認します。リクエスト本文に個人情報、顧客データ、シークレットが含まれる場合は、監査ログへ全文を複製せず、必要なrequest IDと安全な診断情報だけ記録します。

AnthropicのAPIはJSON error bodyにerror type/messageとrequest_idを含め、応答にはrequest-id headerも返すと説明されています。request IDはサポートへ特定リクエストを照会するときの情報になります。API keyそのもの、Authorization header、顧客データ、完全なpromptは一般ログや問い合わせ文へ貼らないでください。

最低限の記録欄：

・HTTP statusとerror.type

・error.messageの機密除去済み要約

・request-id、時刻、endpoint、model

・発生回数、連続回数、影響リクエスト数

・並列リクエスト数、retry回数と間隔

・429の場合は使用可能なrate-limit / retry-after情報

・Claude Consoleや公式statusで確認した時刻と状態

・再試行した結果と、最終的な成功・中断・escalation

529と429をまず分ける

529 overloaded_errorはAPIが一時的に過負荷になっていることを示します。ドキュメントは、全利用者にわたる高トラフィック時に529が発生し得ると説明しています。したがって529を見た瞬間に、アカウントの月間spend capやrate limitを超えたと決めつけないでください。まずstatusとerror.typeが実際に529/overloaded_errorか確認し、短い時間に同じリクエストを大量に再送していないか、同時実行やqueueが急増していないかを調べます。

429 rate_limit_errorは、組織のrate limit、利用tierのmonthly spend cap、またはClaude Code workspace spend limitに関係する応答として説明されています。API docsによると、tierのspend-capに関する429はretry-after headerがなく、利用可能状態へ戻るまで繰り返し失敗する場合があります。429を受けたらその応答に含まれる利用制限情報、組織のtier・利用状況、Console側のspend limitを確認します。429はすべて同じ理由ではないため、エラー本文とheaderを確認せず「料金上限」と断定しないでください。

一時的な高負荷を避けるため、429の一部では急激な利用増加に対するacceleration limitもあり得ると公式資料が説明しています。この場合、trafficを一気に増やすのではなく、負荷を徐々に上げて安定した利用パターンにすることが対策候補です。これは429の補助的な可能性であり、すべての429や529の根本原因ではありません。

区別の例：

・HTTP 529 + overloaded_error：API一時過負荷の分岐へ。並列度・再試行・公式statusを確認。

・HTTP 429 + rate_limit_error：組織rate limit、tier spend cap、Claude Code workspace制限等の分岐へ。利用状況と応答headerを確認。

・HTTP 500 + api_error：API内部エラーの分岐へ。公式資料は指数backoffでの再試行を案内。

・HTTP 401 + authentication_error：API key等の認証問題。529としてretryしない。

・HTTP 402 + billing_error：支払い・billing情報の分岐。負荷制御だけで解決しない。

・HTTP 200後にstreaming中のerror event：通常のHTTP response errorと同じ処理だと仮定せず、streamingのerror event仕様で扱う。

エラータイプは将来増える可能性があるとAnthropicが説明しています。コード文字列を無制限に固定した分岐にせず、既知のstatus/typeは分類しながら、未知のerror typeも安全にログ・停止・調査できるfallbackを用意します。message文字列だけに依存して自動処理を切り替えないでください。

529の再試行を安全に設計する

最初に「retryしてよい操作か」を確認します。読み取りに近い生成要求と、外部システムへの副作用を伴う処理では、再送の影響が異なります。529は一時過負荷の可能性を示しますが、アプリが同一処理を何度実行しても安全だという保証ではありません。外部DB更新、メール送信、決済などと結びつく処理は、アプリ側の重複防止・idempotency設計を確認してから再試行します。

次にretry budgetを決めます。429や5xxを見た瞬間に同じ呼び出しをループするのではなく、回数上限、全体deadline、queue上限、キャンセル条件を定めます。待ち時間は指数backoffを基本にし、サービスがretry-afterを返した場合はその値を尊重します。複数workerが同時に再送して負荷の波を作らないよう、必要ならrandomized jitterを組み合わせ、失敗中は新規送信量を絞ります。公式SDKは一時的な失敗、rate limit、5xx等を対象に指数backoffで既定2回再試行し、retry-afterを尊重すると説明されています。SDKを使う場合、アプリ独自の再試行とSDK内部の再試行を二重にしていないか確認します。

直接HTTP clientを使う場合は、SDKと同一の挙動が自動であるとは限りません。API responseのstatus・body・headerから再試行可否を判断する実装が必要です。529に対しては、限定回数の遅延再試行を行い、連続失敗時はqueueへ戻す・処理を保留する・運用担当へ通知するなどの停止経路を設けます。retry-afterがないから即時再送してよい、という意味ではありません。

429では、まず利用制限の原因を確かめます。rate limitに当たっているならリクエスト頻度やtoken throughputを利用枠に合わせます。spend capならConsoleで利用状態・制限を管理者が確認します。tier spend capのようにretry-afterがない429は、そのままretryを続けても回復しないことがあるため、Consoleや組織の制限解除を確認するまでpauseします。rate limitが解消する前にretryを重ねても、追加の処理成功や利用枠増加を保証しません。

負荷を落とす方法はシステムに合わせて選びます。例えば、同時実行上限を下げる、queue worker数を制限する、失敗中の新規要求を一時保留する、同一ユーザーの連打をまとめる、バックグラウンド処理を段階的に再開するなどです。ただしAPIのrate limitを回避するために複数keyや複数organizationへ要求を分散するような不適切な回避策は採用しません。所属組織の利用条件とAnthropicの制限に沿って運用します。

streamingと非streamingで失敗点が違う

Messages APIをstreamingで使うと、通常のHTTP responseが200で始まった後にSSE stream内でerror eventが発生することがあります。AnthropicのAPI errors資料は、その場合のerror handlingは一般的なHTTP status errorの仕組みとは異なると案内しています。HTTP 200だけで生成完了と判断せず、SSEのevent sequenceが正常終了したか確認してください。途中のerror eventを見落としてpartial outputを完成結果として保存しないようにします。

非streamingなら、HTTP statusとJSON error bodyを確認してから処理を再試行します。streamingでは、受信済みのpartial output、途中イベント、終了event、アプリ側の保存状態を確認し、途中までの内容を同じ利用者へ二重に送らない設計を取ります。再試行時に同じ内容を新しい呼び出しで再生成するのか、部分結果を破棄するのかは、アプリの仕様と副作用に合わせて決めてください。

SDKの自動retryを使う場合でも、streamingの中断後にアプリがどこまで内容を受け取ったか確認します。全体結果を待つSDK helperを使うのか、eventを逐次処理するのかでエラーの見え方が変わることがあります。API errorsとstreaming docsに記載されたエラー形状を確認し、status codeだけを見る古い監視ロジックを見直します。

負荷と利用制限の監視

運用者は、status code別の回数だけでなく、error.type、request ID、呼び出し先、実行時間、並列数、retry回数、成功率を追跡します。529が短時間に増えたら、公式status情報と内部の交通量を同じ時間軸で比較します。公式statusの障害情報が見当たらなくても、個別の過負荷応答がないと断定することはできません。逆に、組織内の同時送信急増だけを根拠に「Anthropic全体の障害」と断定しないでください。

429の調査では、rate-limit headersが利用可能なら該当bucketのlimit、remaining、reset情報を記録し、組織・workspaceのspend limitやtier利用状態と見比べます。headerがないこと自体を、制限がない証拠とは扱いません。API docsがtier spend-cap 429ではretry-afterを返さず継続失敗する可能性を示しているため、応答bodyとConsoleの情報が重要です。

本番アプリでは、1件の529と継続的な529を別のアラートにします。1件だけならbounded retryで復旧するか観察できますが、一定時間・件数を超えて続けば送信量を抑え、利用者に保留状態を示し、request IDをまとめてサポートへ相談します。retryのたびに元requestを再ログ・再送し続ける設計は、利用コストや重複処理を増やすため避けます。

対応フロー：1件のエラーから復旧まで

  1. API responseのHTTP status、error.type、message、request-idを取得する。SDKならtyped exceptionとraw response情報も確認する。

  2. streamingならHTTP statusだけでなくSSEのerror eventと正常終了を確認する。

  3. 529 overloaded_errorか429 rate_limit_errorか、または別のstatusかを分類する。

  4. 529なら公式statusと内部traffic・concurrencyを確認し、負荷を抑えてbounded backoff retryへ進む。

  5. 429ならrate limit、tier spend cap、workspace spend limit、acceleration limitの可能性を応答情報とConsoleで切り分ける。

  6. 429が継続しretry-afterもないspend-capケースでは、自動retryを止めて利用状況・制限解除を確認する。

  7. 同一処理の再実行が安全か、副作用・重複防止・partial outputを確認する。

  8. retry回数、待機、成功・失敗を記録し、継続するならrequest IDを添えてサポートへ引き継ぐ。

  9. 回復後は新規trafficを段階的に戻し、429/529の再増加、成功率、queue遅延を監視する。

このフローは原因をstatus codeだけで決めず、API応答と組織の利用状態を組み合わせます。モデル・サービスtier・organization・workspaceで適用条件が異なることがあるため、数値のrate limitやspend capはここで固定しません。実際の契約・利用枠はClaude Consoleとアカウントに適用される公式のrate limit情報を確認してください。

Incident記録テンプレート

時刻（UTC/JST）：

Endpoint / model：

HTTP status：

error.type：

error.message（secret除去済み）：

request-id：

streaming / non-streaming：

発生回数・連続回数：

retry回数・待機時間：

並列度・queue状況：

429 rate-limit headers / reset情報：

Console利用上限確認時刻：

公式status確認時刻：

実行した変更と承認者：

最終結果・次の担当：

個人情報や顧客データを含むprompt全文は、障害票に自動添付しない方針にします。必要なケースでサポートへ提供するときは、組織のデータ取扱ルールとAnthropicのサポート手順に従い、request IDなど最小限の診断情報から始めます。

よくある誤対応

・529を429と同じrate limitと見なして、組織のspend capだけを確認して終える。

・429をすべてspend capと決めつけ、rate limitや応答headerを確認しない。

・529へ遅延なしの即時retryを無制限に行い、混雑やqueueを増やす。

・SDK retryとアプリretryが重なり、想定より多くの再送を発生させる。

・streaming responseがHTTP 200だったため、後続SSE error eventを無視する。

・retryを副作用のある処理へ適用し、外部書き込み・通知・課金を重複させる。

・retry-afterがないことを無制限の再送許可と解釈する。

・存在する特定organizationの状況を見ずに、Anthropic全体の障害や自社の上限超過を断定する。

・request IDを残さず「APIが失敗した」とだけ記録する。

処理を閉じる前に、status/typeに合った原因分岐を選んだか、再送回数が上限内か、partial outputを完成扱いしていないか、request IDを保存したかを確認します。429または529が再発する場合は、同じretryを繰り返さず、負荷・上限・Console状態・公式status・対象時刻を再調査します。

公式資料

Anthropic Claude Platform Docs｜Claude API errors

https://platform.claude.com/docs/en/api/errors（新しいタブで開く）

確認日：2026-10-15

Anthropic Claude Platform Docs｜Rate limits

https://platform.claude.com/docs/en/api/rate-limits（新しいタブで開く）

確認日：2026-10-15

Anthropic Claude Platform Docs｜Streaming messages

https://platform.claude.com/docs/en/build-with-claude/streaming（新しいタブで開く）

確認日：2026-10-15