API Error: 529 Overloaded

API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

Claude CodeやClaude Desktop、Claude APIを利用していると、上記のような「529 Overloaded」というエラーメッセージが表示されることがあります。これは皆さんの設定ミスや使いすぎが原因ではありません。Anthropic側のサーバーが一時的に混み合っている状態を示すエラーで、多くの場合は少し時間を置いてから再試行すれば解消します。

529 Overloadedは何を意味するか

「529 Overloaded」は、Anthropicが提供するサーバー全体が一時的に処理能力の上限に達していることを示すエラーです。HTTPのステータスコードは529で、エラーの種類を表すerror type(エラーの分類を示す文字列)はoverloaded_errorとなっています。

これは利用者個人のアカウントに問題があるわけではありません。Anthropicのインフラ全体で処理が混み合っている状態を指しており、特定の誰かが使いすぎたから発生するものではなく、多くの利用者が同時にアクセスした場合などに一時的に起こります。

Claude APIから実際に返ってくるレスポンス(応答データ)は、次のような形です。

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

実際の運用では、この形に加えてrequest_id(そのリクエストを一意に識別するためのフィールド)が付加される例も報告されています。

429との違いを押さえる

Claudeを使っていると、529と似たエラーに429があります。どちらも「今は処理できません」という趣旨のエラーですが、原因の所在が違います。

429(rate_limit_error)は、利用者やその組織に割り当てられたレート制限、または利用上限に到達したときに返されるエラーで、原因は自分側にあります。一方529(overloaded_error)は、Anthropicのインフラ全体が一時的に容量超過している状態を示すため、原因は提供側にあります。原因の所在が違う以上、対処の方向性も変わります。429は送信ペースの調整やプランの見直しが必要ですが、529は基本的に時間を置いた再試行で解決します。

Claude APIの公式エラーリファレンスでは、ステータスコードとerror typeの対応が次のように定義されています。

なお、503(Service Unavailable)はこの公式のエラー一覧には含まれていません。

まず確認すること

529や5xx系のエラーに遭遇したら、まずClaudeが繋がらない・エラーが出たときに最初に確認するページでAnthropic側の状況を確認しましょう。

確認先は https://status.claude.com/ です。このページでは、claude.ai、Claude Console、Claude API、Claude Code、Claude Cowork、Claude for Governmentといったコンポーネント(機能・サービスの単位)ごとに、稼働状況が個別に掲載されています。どのサービスで障害が起きているのかを切り分けて確認できます。

Claude Codeを使っている場合、5xx系や529のエラーが発生すると、このステータスページへのリンクがエラーメッセージと一緒に表示される仕組みになっています。

Bedrock / Vertex AI / Foundry経由の場合

注意したいのは、Amazon Bedrock、Google Vertex AI、Microsoft Foundryといったクラウドサービス経由でClaudeを利用している場合です。status.claude.comはAnthropicが直接運用しているサービスだけを対象としており、これらのクラウド経由の利用は対象外です。クラウド経由でエラーが出た場合は、利用しているクラウドプロバイダ自身のステータスページを確認してください。

待つ以外にできること（Claude Code利用者向け）

Claude Codeには、529のような一時的なエラーに対応するための設定がいくつか用意されています。コードを書かない方でも、起動時のオプションや環境変数を設定するだけで利用できます。

主モデルが過負荷や利用不可の状態になったとき、--fallback-modelフラグ、または設定ファイルのfallbackModel項目を使うと、最大3つのフォールバックモデル(代わりに試すモデル)を順番に試行させられます。

# 起動時にフォールバックモデルを指定する例(モデル名は利用環境に合わせて指定)
claude --fallback-model <フォールバック先のモデル名>

リトライの回数はCLAUDE_CODE_MAX_RETRIESという環境変数で設定できます。上限は15回です。

# リトライ回数の上限を設定する例(上限は15)
export CLAUDE_CODE_MAX_RETRIES=15

ストリーミング(応答をリアルタイムで少しずつ受け取る方式)の途中で過負荷やサーバーエラーが発生しても、それまでに生成された部分的な応答が丸ごと消えることはありません。不完全な応答であることを示す通知付きで、書きかけの出力が保持される仕組みになっています。

また、Web検索やWebフェッチのツールを使っている場合は、529が発生しても一定の間隔を空けながら自動的に再試行する仕組み(バウンデッドバックオフ)が組み込まれています。

開発者向け: SDKのリトライ設定

ここからは、Claude APIを直接呼び出す開発者向けの内容です。PythonパッケージのanthropicとTypeScriptの@anthropic-ai/sdkには、どちらも自動リトライの仕組みが組み込まれています。

既定では2回まで自動的にリトライされますが、max_retriesを明示的に指定すれば回数を増やせます。

import anthropic

client = anthropic.Anthropic(max_retries=5)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ maxRetries: 5 });

エラーの内容によって処理を分けたい場合は、メッセージ文字列の一致で判定するのではなく、型付きのエラークラスを使うことが推奨されています。Pythonであれば、次のようにanthropic.APIStatusErrorのstatus_codeを見て分岐させる形が基本です。

import anthropic

try:
    client.messages.create(
        model="<使用するモデル名>",
        max_tokens=1024,
        messages=[{"role": "user", "content": "こんにちは"}],
    )
except anthropic.APIStatusError as e:
    if e.status_code == 529:
        print("Anthropic側が一時的に過負荷です。時間を置いて再試行してください。")
    else:
        raise

それでも止まるときの設計側の対処

どうしても529が頻発して困る場合は、そもそも同期的なAPI呼び出しに依存しない設計に切り替えるという選択肢もあります。

Message Batches APIは、目安として10分を超えるような処理に向いた仕組みです。リクエストをまとめて送信し、結果はポーリング(一定間隔での問い合わせ)で受け取ります。同期的なAPI呼び出しと比べてコストが50%削減されるうえ、ポーリング方式のためネットワークが切断されるリスクを避けられるという利点があります。

Batchesを使う場合は、1時間キャッシュでのプロンプトキャッシュ(同じ内容を再送する際の処理を省略する仕組み)を併用することが案内されています。処理量が多い場合は、あわせて検討する価値があります。

英語版 / English version

海外のフォーラムやGitHub Issueなどにそのまま貼り付けられるよう、ここまでの内容を英語でもまとめました。必要な方はコピーしてお使いください。

API ERROR: 529 OVERLOADED - WHAT IT MEANS AND WHAT TO DO
==========================================================

If you see this message:

"API Error: 529 Overloaded. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com."

...it is not a mistake in your account or your code. A 529 means Anthropic's infrastructure is temporarily over capacity. The error type string is "overloaded_error". The response body looks like this:

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

Production responses have also been reported to include a "request_id" field, which uniquely identifies the request.

529 VS 429
----------
A 529 (overloaded_error) differs from a 429 (rate_limit_error). A 429 means you or your organization hit a rate limit or usage cap, so the cause is on your side. A 529 means Anthropic's infrastructure as a whole is temporarily overloaded, so the cause is on Anthropic's side. Note that 503 is not listed in Anthropic's official error reference.

WHERE TO CHECK
---------------
Check https://status.claude.com for live status per component: claude.ai, Claude Console, Claude API, Claude Code, Claude Cowork, and Claude for Government. Claude Code links to this page on a 5xx or 529 error. Exception: if you access Claude through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry, status.claude.com does not cover those. Check your cloud provider's own status page instead.

FOR CLAUDE CODE USERS
----------------------
Set a fallback model with the --fallback-model flag or the fallbackModel config option, up to three models. CLAUDE_CODE_MAX_RETRIES controls retry count, up to 15. If a 529 or server error happens mid-stream, the partial output already received is kept, marked incomplete, not discarded.

FOR DEVELOPERS (SDKs)
----------------------
The Python "anthropic" package and the TypeScript "@anthropic-ai/sdk" both retry automatically on connection errors, 408, 409, 429, and 5xx (including 529), with 2 retries by default and exponential backoff. A retry-after header, if present, is honored. Set max_retries at client creation, e.g. Anthropic(max_retries=5) in Python or new Anthropic({ maxRetries: 5 }) in TypeScript. Branch on the typed error class and its status_code rather than the message string.

IF IT KEEPS HAPPENING
-----------------------
For workloads that can tolerate latency, roughly 10+ minutes, consider the Message Batches API: 50 percent cheaper than synchronous calls, and polling avoids the risk of a dropped connection. Batches also pairs well with 1-hour prompt caching.

参考資料

• https://platform.claude.com/docs/en/api/errors — Claude APIの公式エラーリファレンス。ステータスコードとerror typeの対応表を掲載
• https://platform.claude.com/docs/en/api/rate-limits — レート制限に関する公式ドキュメント
• https://status.claude.com/ — Claude関連サービスの稼働状況を確認できる公式ステータスページ
• https://github.com/anthropics/anthropic-sdk-python — Anthropic公式Python SDKのリポジトリ
• https://github.com/anthropics/anthropic-sdk-typescript — Anthropic公式TypeScript SDKのリポジトリ
• https://platform.claude.com/docs/en/build-with-claude/batch-processing — Message Batches APIの公式ドキュメント
• https://platform.claude.com/docs/en/build-with-claude/prompt-caching — プロンプトキャッシュの公式ドキュメント