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 では、一見似たようなエラーメッセージが、実際にはまったく異なる問題に対して表示されることがあります。 しばらく待つと消えるものもあります。 それは来月まで消えません。

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

529 の対処方法

1. 再試行する前に、状態コードを確認してください。 529 と 429 ではそれぞれ異なる待機時間が必要であり、retry-after がない 429 の場合は再試行が必要ありません。
2. 529 の場合はバックオフします。 指数バックオフとランダム ジッターを使用して再試行し、数回試行した後に停止します。 応答に retry-after ヘッダーが含まれている場合は、その時間だけ待機します。
3. 最初の再試行はSDKに任せます。 公式Anthropic SDK では、接続エラー、レート制限、5xx エラーに対して、指数バックオフを使用して既定で 2 回再試行を行い、存在する場合はretry-afterに従います。 max_retries (TypeScript ではmaxRetries) でカウントを変更できます。 SDK の再試行回数が尽きると、コードでエラーが発生します。
4. 支出上限に達した場合の再試行を停止します。 429 ステータス コードに retry-after ヘッダーが含まれていない場合は、ユーザーにその旨を伝え、自身でも注意してください。
5. ユーザーに情報を提供します。 処理をキューに入れ、後で再試行するか、あるいは一般的なエラーメッセージではなく、「現在処理中です。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 ユーザーからのトラフィックに依存するため、トリガーすることはできません。 どのようにテストするかによって、ユーザーより先にバグを見つけられるかどうかが左右されます。

アプリで試す

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"

どちらのプリセットにも支出上限 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 の再試行回数が尽きた場合に何が起こるかを確認するには、Dev Proxy を --failure-rate 100 で起動してください。 詳細については、「変更リクエスト失敗率」を参照してください。 Dev Proxy をインストールするには、「Dev Proxy のセットアップ」を参照してください。

次のステップ

参照

• 429 リクエストが多すぎます: それが何を意味し、どのように処理するか
• API からの 500、502、503、504 エラー: その意味と処理方法
• スロットリングとは何ですか？
• アプリケーションがスロットルを適切に処理することをテストする