Claude API のエラー 529 overloaded_error — 意味と対処法

529 は、コードが原因ではない Claude の唯一のエラーです。Anthropic 自体が過負荷になっています。修正はできませんが、うまく吸収することはできます。つまり、忍耐強いリトライ、予備モデル、そして即時再試行によってインシデントを決して増幅しないことが重要です。

エラー

resposta (HTTP 529)

{
  "type": "error",
  "error": { "type": "overloaded_error",
             "message": "Overloaded" }
}

原因と対処法の概要

原因	対処法
プロバイダーの飽和（リリース日、地域インシデント）	ジッター付き指数バックオフ。デプロイをやり直すのではなく、プロバイダーのステータスページを確認してください。
部分的なインシデント中にトラフィックのピークが発生した	ジョブをバッチに分散してください。通常は10分待てば解決します。
ループで即時リトライする	すぐに再試行すると負荷が倍増し、あなたを含む全員に影響するインシデントが長引きます。

良き市民としてリトライする

529 は retry-after ヘッダーのない 429 として扱います。約2秒から始めるジッター付き指数バックオフ、30〜60秒の上限、約5回での打ち切り、そしてジョブのキューイングを行います。429 を処理するコード分岐をそのまま 529 にも使用できます。

retry.py

import time, random
from openai import APIStatusError

def com_retry(fn, tentativas=5):
    for i in range(tentativas):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            espera = min(2 ** i + random.random(), 60)
            time.sleep(espera)
    raise RuntimeError("esgotou as tentativas")

フォールバックするのではなくモデルを切り替える

レイテンシー重視の経路には予備モデルを設定します。同じファミリー内（Sonnet → Haiku）なら挙動が似たままですが、プロバイダー間（Claude → GPT）ならインシデント全体を乗り切れます。OpenAI 互換エンドポイントなら、文字列を1つ変更するだけです。

failover.py

PREFERIDOS = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

def completar(mensagens):
    ultimo = None
    for modelo in PREFERIDOS:
        try:
            return client.chat.completions.create(
                model=modelo, messages=mensagens, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            ultimo = e          # saturado — tenta o próximo
    raise ultimo

529 を 429 や 402 と混同しない

429 は制限を超えたことを意味します（サーバーは正常です）。529 はサーバーが過負荷であることを意味します（あなたのクォータは正常です）。402 は残高不足を意味します。ログ上では3つとも似ていますが、対処法は完全に異なります。再試行すべきなのは 429 と 529 だけです。

Kunavo経由で呼び出している場合

Kunavo では、同じマルチモデルカタログを1つのキーと1つのウォレットの背後で利用できるため、上記の例でのプロバイダー間フェイルオーバーはモデル名を変更するだけです。2つ目のアカウントや登録は必要ありません。失敗したリクエストには課金されません。容量と価格は別の問題です。後者については、トークン単価を Claude APIの料金ガイド.

よくある質問

529 エラーは私のせいですか？

いいえ。プロバイダー側の容量の問題です。あなたの責任は、バックオフとジッターで問題を増幅しないこと、そしてインシデントがレイテンシー予算を超えて続いた場合に移行先を用意することだけです。

529 と 429 の違いは何ですか？

429 は制限を超えたことを意味し、529 はサーバーが過負荷であることを意味します。どちらもリトライできますが、通常 retry-after のヒントが付くのは 429 だけです。

529 になったリクエストにも課金されますか？

課金されないはずです。リクエストはトークンを生成していません。Kunavo では、失敗したリクエストは残高から差し引かれません。