APIエラー529「Overloaded」: リトライ、バックオフ、フォールバック戦略

本番ログに 529 overloaded_error が表示される場合、プロバイダーは API が一時的に過負荷であることを示しています。Anthropic の Claude API ドキュメントでは、529 - overloaded_error は「API は一時的に過負荷です」を意味し、529 エラーは全ユーザーにわたる高トラフィック時に発生しうると記載されています。

そのため、APIエラー529「Overloaded」: リトライ、バックオフ、フォールバック戦略 は、形式が壊れたリクエスト、不正な API キー、あるいは通常のクォータ問題とは異なります。最初の対応は「プロンプトを変更する」でも「クォータを追加購入する」でもありません。最初の対応は、制御された信頼性のプレイブックです。障害を分類し、予算内でのみリトライし、リトライの嵐からユーザーを守り、待つよりフォールバック経路のほうが安全かどうかを判断します。

このガイドは、本番環境で LLM、エージェント、またはマルチモーダルのワークロードを運用する AI プロダクトチームおよびプラットフォームチーム向けに書かれています。インシデント対応手順書にそのまま組み込める実用的なエラー対応マトリクス、リトライ予算、バックオフパターン、フォールバックの判断フローを提供します。

簡潔な答え

APIエラー529「Overloaded」: リトライ、バックオフ、フォールバック戦略 では、次のデフォルトポリシーを使用してください。

1. 529 overloaded_error は、クライアント側の検証バグではなく、プロバイダーの一時的な容量不足のシグナルとして扱う。
2. 冪等または読み取り専用のリクエストは、指数バックオフとジッターを付けて再試行する。
3. プロバイダーが retry-after を返す場合はそれに従う。
4. 特にインタラクティブなトラフィックでは、通常 2 回または 3 回程度の少ないリトライ予算で停止する。
5. 冪等でないツール呼び出し、書き込み操作、購入、メール送信、または副作用を引き起こした可能性のあるものは、盲目的に再試行しない。
6. 529 がプロバイダー、モデル、エンドポイント、またはリージョン単位で集中したら、サーキットブレーカーを開く。
7. 代替モデルが同じプロダクト契約を満たせる場合にのみフォールバックする。
8. request-id、モデル、ルート、リトライ回数、最終結果、ユーザーに見える影響をログに記録する。

要するに、短時間だけ再試行し、負荷を抑え、同等性が許容できる場合にフェイルオーバーし、要求を安全に繰り返せなくなったら停止するということです。

APIエラー529 Overloaded が発生する理由

529 overloaded_error は容量に関する状態です。通常は、リクエストがプロバイダーには到達したものの、その時点でプロバイダー側が忙しすぎて処理できないことを意味します。Anthropic はこれを 429 rate_limit_error とは別に文書化しています。この違いは重要です。

529 は、あなた自身のワークロードに何も異常がなくても、プロバイダー全体でトラフィックが急増した際に発生することがあります。ただし、新機能のリリース、バッチ処理の実行、あるいは突然のエージェント群の送信を行っている場合は、トラフィックの立ち上がりがローカルな負荷や加速制限の挙動を引き起こしていないかも確認すべきです。

エラー-アクション表

パニックになってコードを変更する前に、この表を使ってください。

これこそが、ほとんどの一般的なエラーページが見落としている点です。過負荷のモデルは単なる HTTP ステータスではありません。重複作業、レイテンシ、出力品質、そしてユーザーの信頼に関するプロダクト上の判断なのです。

529 のための安全なリトライポリシー

まず、対話型ワークロードとバックグラウンドワークロードで別々のリトライ予算を設定します。

最もシンプルなリトライの形は、ジッター付きの指数バックオフです:

function backoffMs(attempt: number) {
  const base = 250;
  const cap = 8_000;
  const exponential = Math.min(cap, base * 2 ** attempt);
  const jitter = Math.floor(Math.random() * exponential * 0.4);
  return exponential + jitter;
}

対話型のプロダクトでは小さな値を使ってください。60 秒間リトライし続けるチャットメッセージは、技術的には耐障害性があっても、ユーザーには壊れているように感じられます。バックグラウンドキューでは、より広いバックオフウィンドウを使い、プロバイダーを叩き続ける代わりに、後で処理するために作業アイテムを保持してください。

Retry-After を尊重するが、依存しない

一部の API は、レート制限や一時的な障害に対して retry-after ヘッダーを返します。Anthropic のドキュメントでは、公式 SDK は指数バックオフで一時的な障害を再試行し、デフォルトでは 2 回まで試行し、retry-after が存在する場合はそれに従うと説明されています。SDK をバイパスする場合やラップする場合でも、独自のコントローラは同じ動作にすべきです。

ただし、retry-after が存在する場合にのみ機能するポリシーは作らないでください。529 レスポンスには、常に有用な待ち時間が付いてくるとは限りません。フォールバック用コントローラには、引き続き次のものが必要です。

• 最大試行回数
• 最大の実時間予算
• ルートごとのサーキットブレーカー
• キュー滞留時間の上限
• そして最終的なユーザー向け失敗モード

再試行ストームを避ける

プロバイダの過負荷に対する最悪の対応は、再試行トラフィックが同期してしまうことです。すべてのワーカーが即座に再試行すると、1 件のプロバイダ障害をさらに大きな障害にしてしまいます。

次の制御を追加してください。

AWS の retry-with-backoff ガイダンスも同じ運用上の点を示しています。再試行は一時的な障害には有効ですが、再試行が多すぎると競合を増やし、サービスの劣化を招く可能性があります。

再試行ではなくフォールバックを使うべきとき

フォールバックは再試行と同じではありません。再試行は同じルートにもう一度試すよう求めます。フォールバックはルート、プロバイダ、モデル、リージョン、または機能を変更します。

次の 4 条件がすべて真である場合にフォールバックを使ってください。

1. 主要ルートが 529 または関連する一時的エラーで繰り返し失敗している。
2. 追加の遅延後でも、ユーザーまたはワークロードがレスポンスから利益を得られる。
3. 代替ルートが同じ製品契約を満たす。
4. リクエストがすでに部分出力や不確実な副作用を発生させていない。

次のようなルート契約を使ってください。

task: support_reply_draft
primary:
  model: claude-sonnet-current
  max_attempts: 2
  retry_on: [529, 500, 502, 503, 504, timeout]
  backoff: exponential_jitter
fallback:
  model: approved-general-chat-model
  allowed_when:
    - no_partial_stream_output
    - no_write_side_tool_executed
    - response_schema_compatible
    - latency_budget_remaining_ms > 3000
stop:
  user_message: "The model is overloaded. Please retry in a moment."
log:
  fields:
    - request_id
    - route
    - model
    - retry_count
    - fallback_used
    - final_status

製品が厳密なモデル動作、ツール呼び出し形式、引用ポリシー、安全性の挙動、または長文コンテキスト機能に依存している場合、クロスモデルのフォールバックは明確な失敗より悪いことがあります。そのようなワークロードでは、別のモデルファミリーにフォールバックするよりも、同じプロバイダ/モデルを別ルートで使うフォールバックのほうが安全です。

この判断の背後にあるより広いアーキテクチャについては、このエラーページを Flatkey のLLM API フォールバックルーティング本番運用プレイブックおよびモデルフォールバック戦略ワークフロープレイブックと組み合わせてください。これらのガイドは、より大きなコントローラパターンを扱っています。このページは 529 の overloaded 応答に焦点を絞っています。

529 の冪等性ルール

リトライの安全性は冪等性に依存します。AWS のガイダンスでは、バックオフ付きで再試行する場合、操作は冪等であるべきだと指摘されています。そうでないと、部分的な更新によって状態が破損する可能性があります。Stripe の低レベルなエラーガイダンスも、ネットワークエラーやサーバーエラーについて同じ点を述べています。失敗した、あるいは不明瞭なリクエストにより、サーバーがリクエストを受信したのか実行したのかをクライアントが確信できない場合があるためです。

AI 製品では、このルールをツールと副作用に適用してください:

実践的なルールはシンプルです。繰り返しリクエストによって外部状態の重複が発生する可能性があるなら、汎用的なリトライラッパーにそれを委ねないでください。

サーキットブレーカーのしきい値

サーキットブレーカーは、繰り返される過負荷を一時的なルーティング判断に変えます。始めるのに複雑なシステムは必要ありません。

次のようなポリシーを使用してください:

• 2 分間であるルートの 529 が試行全体の 20% を超え、かつ少なくとも 20 件のリクエストが試行された場合に回路を開く。
• 対話型トラフィックでは、回路を 60〜180 秒間開いたままにする。
• 回路を閉じる前に、少数のプローブリクエストを送る。
• 徐々にリセットする。キュー全体を一度にそのルートへ戻さない。
• 可能であれば、プロバイダー、モデル、エンドポイントファミリー、リージョンごとに回路状態を追跡する。

サーキットブレーカーは、エージェントシステムで特に重要です。エージェントはしばしば、モデル SDK、オーケストレーションライブラリ、ジョブワーカー、ユーザーコマンドループという複数の層で再試行するからです。各層を数えないと、リトライ予算を意図せず増やしてしまう可能性があります。

可観測性チェックリスト

529 インシデントごとに、何が失敗したのか、なぜ再試行されたのか、フォールバックが発生したかどうか、そしてユーザーに何が見えたのかという 4 つの質問に答えられるだけの証拠を十分に記録してください。

Flatkey チームは https://router.flatkey.ai/v1 でも同じパターンを使えます。1つの OpenAI 互換ベース URL 経由でルーティングし、モデル選択を明示的に保ち、インシデント後に利用ログを確認します。Flatkey のクイックスタートでは、共有キー、モデルカタログ、ルーターのベース URL、Usage Logs が、リクエストトラフィックとコストを確認する場所として文書化されています。

レート制限の扱いと過負荷の扱いをまだ分けているなら、429/RPM/TPM ポリシーについては LLM rate limits guide を、信頼性レポートについては AI routing API metrics guide を参照してください。

Flatkey が 529 復旧計画にどう適合するか

Flatkey は、過負荷が起こりえないふりをするためのものとして扱うべきではありません。上流のモデルプロバイダーが依然として混雑していることはあります。ゲートウェイにとって有用な役割は、運用上の制御です。

• モデルトラフィック用の 1 つの OpenAI 互換ベース URL。
• 承認済みフォールバック候補のための共有モデルカタログ。
• リトライと回復した失敗のための 1 つの利用・コスト台帳。
• すべてのアプリケーションクライアントを書き換えることなく、ルーティングポリシーをより迅速に変更できること。
• プロダクト、プラットフォーム、財務の各チームがインシデントをレビューする際の、より明確な監査証跡。

本番チームにとって、これは大きなリトライループよりもしばしば価値があります。大きなリトライループは、インシデントが高コストになるまで隠してしまうことがあります。ルーティングされたポリシーは、過負荷を可視化し、制御します。

API エラー 529 の本番ランブック

これをインシデント対応プロセスに貼り付けてください:

1. エラークラスを確認する: 529 overloaded_error、プロバイダー、モデル、エンドポイント、タイムスタンプ、リクエストID。
2. リクエストが読み取り専用、ストリーミング、または書き込み側のいずれだったかを確認する。
3. 指数バックオフとジッターを使って、ルートのリトライ予算を適用する。
4. リクエストが部分的な出力や不確かな副作用を生じた場合は、リトライを停止する。
5. 同じプロバイダー/モデルのルートで 529 が集中している場合は、サーキットブレーカーを開く。
6. 出力、セーフティ、レイテンシー、コストの挙動が互換である、承認済みのルートにのみフォールバックする。
7. レイテンシー予算が切れたら、ユーザー向けメッセージを表示する。
8. インシデント後に、リトライ回数、フォールバック回数、復旧したリクエスト、失敗したリクエスト、および重複防止の証跡を確認する。

FAQ

APIエラー529は429と同じですか？

いいえ。Anthropic のドキュメントでは、529 は API が一時的に過負荷であることを意味し、429 はレート制限エラーです。ログで別のことが証明されるまでは、529 はプロバイダーの過負荷、429 はレート/クォータ/トラフィック形状の問題として扱ってください。

APIエラー529はリトライすべきですか？

はい。ただし、予算内で、かつリクエストを安全に再実行できる場合に限ります。ジッター付きの指数バックオフを使い、存在する場合は retry-after を尊重し、部分的な出力や外部副作用によって再実行が安全でなくなったら停止してください。

529 overloaded エラーには何回リトライすべきですか？

対話型のAI機能では、まず2回のリトライと厳格な実時間の期限から始めてください。バックグラウンドジョブではより多くのリトライを使えますが、キュー滞留時間の上限、デッドレター処理、サーキットブレーカーを用いるべきです。

529の後に自動でモデルを切り替えるべきですか？

フォールバック先のモデルが同じ製品契約を満たせる場合にのみです。モデル固有の挙動、ツール、スキーマ、セーフティポリシー、コンテキスト長が重要な場合、フォールバックには透過的な切り替えではなく、ユーザーに見える「別のモデルで再生成」アクションが必要になることがあります。

529インシデント中にユーザーには何を表示すべきですか？

平易で一時的な状態を示す言葉を使ってください: 「モデルが過負荷です。短時間リトライしています。」 リトライ予算が切れたら、再試行ボタンか性能を落とした代替案を提示してください。ユーザーが詳細を必要とする開発者でない限り、プロバイダー内部の情報は表示しないでください。

最終推奨

最も安全な APIエラー529「Overloaded」: リトライ、バックオフ、フォールバック戦略 の計画は、単一の while retry ループではありません。ルートポリシーです。つまり、一時的な過負荷は短時間リトライし、ジッター付きでバックオフし、非冪等な処理を保護し、失敗の繰り返しにはサーキットブレーカーを使い、代替ルートがユーザー契約を維持できる場合にのみフォールバックします。

チームですでに複数のモデルやプロバイダーを運用しているなら、そのポリシーを1つのゲートウェイの背後に置いてください。Flatkey を使えば、OpenAI互換クライアントを https://router.flatkey.ai/v1 に向け、フォールバック候補を1つのモデルカタログにまとめ、ローンチ後に Usage Logs で復旧した失敗を確認できます。

最初の呼び出しパスが必要なら Flatkey API quickstart から始めるか、ワークロードレベルのルーティング選択を Claude API proxy vs multi-model router で比較してください。

確認したソース

• Anthropic Claude API errors: https://platform.claude.com/docs/en/api/errors
• AWS Prescriptive Guidance, retry with backoff pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html
• Stripe advanced error handling and idempotency: https://docs.stripe.com/error-low-level
• Flatkey documentation index: https://docs.flatkey.ai/index.md
• Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
• Flatkey product overview: /Users/solveainc/.11agents/flatkey/knowledge_base/information/what-we-do/product-overview.md
• Flatkey marketing strategy: /Users/solveainc/.11agents/flatkey/knowledge_base/marketing/strategy.md