529 Overloaded が意味すること
いま上流の容量が逼迫しているという意味で、リクエストが間違っているのではありません。コードを直しても解決せず、リトライ戦略を直すと効きます。
4 つの要点
上流の混雑
サーバー側の容量が逼迫したときに返ります。キーの枠、パラメータ、リクエスト本文とは無関係です。
レート制限に当たっている
自分のレートや枠の上限に触れたのはこちらです。529 と 429 は対処が異なるため、同じ分岐で扱わないでください。
クライアント側で唯一有効な手段
指数バックオフ＋ジッター。即座のリトライは混雑を悪化させ、レート制限にも早く当たります。
構造的な緩和
同じ作業が別の上流に流せるなら、1 社の混雑が停止を意味しなくなります。代償はモデル差の受容です。
529 と 429・503 の違い
529 はサーバー全体がいま過負荷であるという容量の問題で、通常は一時的です。429 は自分のレートや枠の上限に触れた枠の問題。503 は一般にサービス停止や保守中を指します。いずれもリクエストの記述ミスを意味しませんが、対処は異なります。529 はバックオフしてリトライ、429 は速度を落とすか上限を上げる、503 は待機してステータスページを確認。3 つを 1 つの catch にまとめるのが最もよくある誤りです。
議論が周期的に増える理由
新モデルの公開や大規模な移行があるたびに上流の容量は一時的に逼迫し、529 の話題もそれに伴って増えます。こうした波は容量増強とともに収まるのが通例ですが、締め切りを抱えている人にとって「事業者の増強を待つ」は選べる答えではありません。
切り分けの順序
ステータスコードが本当に 529 で 429 ではないことを確認します。レスポンス本文が異なるため、ログでは分けて集計してください。
事業者のステータスページを確認します。広範な障害であれば、クライアント側の変更は緩和にとどまります。
自分のリトライが混雑を増幅していないか確認します。ジッターなし、上限なし、即時再送はいずれも増幅要因です。
リトライの前に、どのコードなのかを見分ける
確認できること
529 は上流の容量混雑を示しリクエスト内容とは無関係である、という意味づけは事業者のドキュメントに明記されています。ジッター付き指数バックオフは広く検証されたクライアント側の対処です。
事実として扱わないこと
「529 は事業者がヘビーユーザーを密かに絞っている」といった主張には裏付けがなく、本ページでは断定しません。529 と 429 の意味の違いは公開文書に明記されており、混同すると誤った対処を選ぶことになります。
2 つの対処
クライアント側のバックオフのみ
実装コストが低く、失敗率を明確に下げられます。ただし上流の混雑が続く間、できるのは待つことだけです。
複数の上流に流せるようにする
1 社の混雑が停止を意味しなくなります。代償はモデルごとの癖の違いを受け入れることで、どの経路にも固有の障害形態があります。
正しいリトライの書き方
要点は 3 つ。第一に固定間隔ではなく指数バックオフ。まず 1 秒、以降は倍々にします。第二にランダムなジッターを加えること。全クライアントが同じ時間だけ待つと同期したリトライの波が起き、かえって混雑が長引きます。第三に上限を設けること。リトライ回数と総待機時間の両方に上限がないと、一度の混雑でタスクキューが際限なく積み上がります。加えて、ストリーミングが途中で切れた場合は先頭から闇雲に再送せず、受信済みの内容が継続可能かをまず確認してください。
QCode にできること、できないこと
できること：混雑時に同じキーで別のモデル系列へ切り替え、単一の上流の回復を待たずに作業を続けられます。できないこと：私たちは事業者ではないため、上流の容量は変えられません。そして明言しておきます —— 私たちにも失敗するリクエストはあります。直近 7 日間に自社側で観測された失敗はゲートウェイの 502 が中心で、529 は 0 件でした。「落ちない」ことを売りにするサービスは、たいてい自社の失敗データを公開していないだけです。提供できるのは複数の経路と確認可能な失敗記録であって、無障害ではありません。
よくある質問
529 が返ったらリクエストのパラメータを変えるべき？
不要です。529 はリクエスト内容と無関係で、max_tokens やモデルのパラメータを変えても、プロンプトを短くしても消えません。変えるべきはリトライ戦略です。
529 と 429 で同じリトライ処理を使ってよい？
推奨しません。529 はバックオフして同じリクエストを再送すべきですが、429 は送信速度を下げるか上限を上げる必要があり、闇雲な再送は制限に当たり続けます。
どのくらい待つのが適切？
一般的には初回 1 秒、以降は倍々にし、ランダムなジッターを加え、リトライ回数と総待機時間の両方に上限を設けます。具体的な数値は許容できる遅延によります。
ストリーミング中に 529 になったら？
まず受信済みの内容が使えるかを確認します。続きから書けるなら続け、無理な場合のみ全体を再送してください。闇雲な再送は課金の重複と混雑の悪化を招きます。
QCode でも 529 は起きますか？
上流の混雑は実在し、私たちも免れません。直近 7 日間の自社観測では失敗は 502 が中心で 529 は 0 件でした。できるのは同じ作業を別のモデル系列へ移せるようにすることで、失敗しないと約束することではありません。
多経路なら単一障害点はなくなる？
いいえ。多経路は「1 つ落ちたら停止」の確率を下げますが、経路ごとに固有の障害形態があり、ルーティング層自体も故障しえます。緩和であって解消ではありません。
情報源
ステータスコードの意味は各社の公式 API ドキュメントに従います。本ページでは第三者による可用性のパーセンテージを意図的に引用していません。そうした数値は時間とともに変動し、参照できる権威ある独立測定がないためです。
関連記事
Claude API エラーコード早見
主要なステータスコードの意味と対処。
Claude Code の利用制限
枠とレート制限の適用のされ方。
モデル切り替えの実践
1 つのキーで複数系列を使う実際。
本ページのステータスコードの意味は各社の公式ドキュメントに従い、バージョンにより変更される可能性があります。記載した自社の失敗観測は自社ログの特定期間のものであり、可用性の保証ではありません。