overloaded_error（529）の原因と対処：Claude APIのリトライ実装

この記事の要点

• overloaded_error は、Claude APIが一時的に過負荷のときに返るHTTP 529のエラーです。全ユーザーのトラフィックが増えたときに起こりえます。
• 利用者側の設定の誤りが原因ではないので、間隔を空けたリトライで対処します。
• ストリーミングでは、HTTP 200を受け取った後にエラーイベントとして届くことがあります。ステータスの確認だけでは捕まえられません。
• リトライで足りないときは、別のモデルへ切り替える処理を用意します。

Overloaded と表示されて処理が止まったときの、原因と実装をまとめます。

overloaded_error のエラー本文

Anthropicのエラーのドキュメントによると、エラーは type と message を持つ error オブジェクトと、追跡用の request_id で返ります。529の場合は次の形です（request_id は一例です）。

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

429との違い

なお、組織の利用量が急に増えると、acceleration limitsによる429が出ることもあります。Anthropicは、トラフィックを徐々に増やすよう案内しています。429全般の対処はLLM APIの429エラーの対処法にまとめています。

ストリーミング中のエラー

ストリーミングでは、200を返した後にエラーが届くことがあります。Anthropicのストリーミングのドキュメントには、次のイベントが例として載っています。

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

途中まで受信した出力が残るので、画面に出した部分をどう扱うかを決めておきます。

リトライと切り替えのコード

Anthropic公式のSDKは、一時的なエラーを既定で2回、指数バックオフで自動リトライします（max_retries で変更できます）。回数を増やすだけなら、この設定で足ります。

次の例はSDKの自動リトライを止め、モデルごとにリトライしてから次のモデルへ移ります。retry-after ヘッダーがあれば従います。

import os
import random
import time

from openai import APIConnectionError, APIStatusError, OpenAI

client = OpenAI(
    api_key=os.environ["FASTMETAL_API_KEY"],
    base_url="https://api.fastmetal.ai/v1",
    max_retries=0,
)

RETRYABLE = {500, 502, 503, 504, 529}


def wait_seconds(err: Exception, attempt: int) -> float:
    if isinstance(err, APIStatusError):
        retry_after = err.response.headers.get("retry-after", "")
        if retry_after.isdigit():
            return float(retry_after)
    return min(30, 2**attempt) + random.random()


def create_with_fallback(models: list[str], messages: list[dict], attempts: int = 4):
    last_error: Exception | None = None
    for model in models:
        for attempt in range(attempts):
            try:
                return client.chat.completions.create(
                    model=model, messages=messages, max_tokens=1024
                )
            except APIStatusError as err:
                if err.status_code not in RETRYABLE:
                    raise
                last_error = err
            except APIConnectionError as err:
                last_error = err
            time.sleep(wait_seconds(last_error, attempt))
    raise last_error


resp = create_with_fallback(
    ["anthropic-claude-sonnet-5", "deepseek-v4.1-flash"],
    [{"role": "user", "content": "こんにちは"}],
)
print(resp.model, resp.choices[0].message.content)

モデルを切り替えると、出力の傾向や対応する機能が変わります。切り替え先は、同じプロンプトで事前に確かめておきます。

FastMetalで別のモデルへ逃がす

FastMetalは、1つのAPIキーで95以上のモデルを呼び出せる日本のAIゲートウェイです。上のコードのように、model の文字列を並べるだけで別の会社のモデルへ切り替えられます。

切り替えの処理を自分で書かない方法もあります。model: "auto" を指定すると、リクエストの条件を満たす中で最も安いモデルにルーティングし、失敗したときは次の候補へ移ります。課金は選ばれたモデルの単価です。単価は料金ページで確認できます。

よくある質問

overloaded_error は課金されますか

エラーで返ったリクエストの課金は、提供元の規定によります。提供元の料金ページとエラーのドキュメントを確認してください。リトライの回数には上限を設けておきます。

何回リトライすればよいですか

決まった回数はありません。対話の画面なら数回で諦めて別のモデルへ移り、夜間のバッチなら長めに待つ、というように用途で決めます。

529が続くときは何を確かめますか

提供元のステータスページで障害が出ていないかを確かめます。自分の組織だけで起きているなら、利用量の急増による制限も疑います。

OpenAIにも同じエラーはありますか

OpenAIでは、モデルの一時的な過負荷は503で、コードは server_is_overloaded です。エラーコードのガイドに載っています。

まとめ

overloaded_error は間隔を空けて待てば通ることの多いエラーです。バックオフのリトライを入れたうえで、長引くときのために別のモデルへ移る経路を用意します。

複数のモデルを1つのキーで使うなら、無料でアカウントを作成できます。