529は、私のコードが作ったものではない唯一のClaudeエラーです。過負荷なのはAnthropic側で、こちらで修正できることはありません。できるのは、きちんと受け止めることだけです — バックオフを伴う辛抱強い再試行、遅延に敏感な経路のためのフォールバックモデル、そして障害を悪化させる即時再試行の集中を避けることです。
エラー
{
"type": "error",
"error": { "type": "overloaded_error",
"message": "Overloaded" }
}原因と対処法の概要
| 原因 | 対処法 |
|---|---|
| プロバイダー側の過負荷（新モデル公開日、地域障害）。すべての顧客に同時に発生します。 | ジッターを加えたバックオフで待ちます。アプリを再デプロイせず、Anthropicのステータスページを確認してください。 |
| 自分のバーストトラフィックが、すでに逼迫した容量と重なっている。 | バッチ処理を時間的に分散します。10分遅らせるだけで、たいてい解消します。 |
| 429との混同。ログでは似て見えますが、原因はまったく異なります。 | 429は自分が制限を超えた状態（サーバーは正常）、529はサーバーが過負荷の状態（自分の制限・残高は正常）。Retry-Afterのヒントが付くのは429だけです。 |
| フォールバックが定義されていないため、プロバイダーの問題がそのまま最終ユーザーに伝わる。 | フォールバック順序を決めておきます。同じ系列（Sonnet → Haiku）なら動作が似ており、プロバイダーをまたげば（Claude → GPT）全面障害にも耐えられます。 |
障害を悪化させない再試行にする
529は「Retry-Afterのない429」として扱います。約2秒から始める指数バックオフ、ジッター、上限30〜60秒、5回程度で諦めてジョブをキューに入れる。重要なのはジッターです。ジッターがなければすべてのクライアントが同じ瞬間に戻り、抜け出そうとしていた過負荷をそのまま延長します。
落とさずに切り替える
遅延に敏感な経路にはフォールバックチェーンを定義します。OpenAI互換エンドポイントなら、変更するのは文字列1つだけです — SDKもアカウントも新しく作る必要はありません：
PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]
def complete(messages):
last = None
for model in PREFERRED:
try:
return client.chat.completions.create(
model=model, messages=messages, max_tokens=800)
except APIStatusError as e:
if e.status_code not in (429, 500, 529):
raise
last = e # 과부하 — 다음 후보로
raise last自分のコードを疑うのは最後
特定のリクエストタイプでだけ529が出て、同じ時刻の他の呼び出しが通るなら、全面障害ではありません。その経路が異常に大きなプロンプトを送っていないか、狭いループ内で連続呼び出ししていないかを確認してください。逆に、すべての呼び出しが一斉に529になって自然に収まったなら、原因は容量です。そのとき手を入れるべきなのは再試行とフォールバックであり、リファクタリングではありません。
Kunavo経由で呼び出している場合
KunavoはClaudeを2つ以上の上流経路へルーティングし、マルチモデルカタログによって、プロバイダーをまたぐフォールバックを「同じキー・同じ残高でモデル名だけを変えること」にしています。上記のコードに2つ目のアカウントは必要ありません。それでも到達した529は課金されません。 容量と価格は別の問題です。2つ目の問題に対するモデル別単価は Claude API料金表.
よくある質問
529は私のせいですか？
いいえ。プロバイダー側の容量問題です。こちらの責任は2つだけです — 障害を増幅しないこと（バックオフとジッター）、そして障害が許容遅延時間を超えた場合に備えた迂回路を用意すること。
529と429の違いは？
429は自分が制限を超えた状態で、サーバーは正常です。529はサーバー自体が過負荷で、自分の制限は正常です。どちらも再試行対象ですが、Retry-Afterのヒントが付くのは429だけです。
529の状態は通常どれくらい続きますか？
予測できず、保証もできません。だから正解は上限を設けたバックオフとキューであり、コードに固定待機時間を書き込むことではありません。その経路に許容遅延時間があるなら、待つ代わりにフォールバックが引き継ぎます。
529で失敗した呼び出しも課金されますか？
Kunavoを経由する場合は課金されません。エラーで終了したリクエストは請求対象外です。直接契約の場合は、各プロバイダーの課金規則に従います。