Claude APIのエラーは、HTTPステータスと応答JSONの error.type を見れば原因の大半を切り分けられます。困るのは、同じ429でも「数秒待てば通るもの」と「翌月まで通らないもの」が混ざっている点です。この記事では、2026年11月7日時点の公式ドキュメントをもとに、ステータス別の意味と再試行の可否、429と529の見分け方、Python SDKのリトライ設定とバックオフの実装コード、status.claude.comでの障害確認、Claude Codeで出るAPI Errorの対処までを実装者向けにまとめました。
まとめ：Claude APIのエラーは再試行してよい種類かどうかを先に判定
最初に決めるのは、そのエラーを再試行してよいかどうかです。429（retry-afterあり）・500・504・529は時間をおけば通る可能性があり、400・401・402・403・404・413は何度送っても同じ結果になります。
注意したいのは、retry-after ヘッダーの無い429です。これは利用ティアの月間支出上限に達した状態で、翌月1日の00:00 UTCまで再試行は成功しません。応答の error.details.error_code が enforced_spend_limit_reached かどうかで判別します。
実装は、公式SDKの自動リトライ（既定2回）に任せるか、SDK側を0回にして自前の関数で一元管理するかの二択です。本番のバッチ処理や業務システムでは後者を採用し、再試行しないエラーは即座に通知へ回します。
Claude APIが返すHTTPエラー11種類とエラー応答JSONの読み方
公式のClaude API errorsには、11のHTTPステータスとそれぞれの error.type が載っています。まず全体像を表で押さえ、次に応答の読み方を確認します。
ステータスコード別のerror.typeと原因・再試行の可否を一覧で比較
次の表は2026年11月7日時点の公式ドキュメントの記載を整理したものです。「再試行」の列は、同じリクエストを時間をおいて送り直す意味があるかを示します。
| HTTP | error.type | 主な原因 | 再試行 |
|---|---|---|---|
| 400 | invalid_request_error | 形式・内容の誤り、自分で設定した支出上限 | しない |
| 401 | authentication_error | APIキーの形式誤り・失効・期限切れ | しない |
| 402 | billing_error | 請求・支払い情報の問題 | しない |
| 403 | permission_error | キーにリソースの権限が無い | しない |
| 404 | not_found_error | パスやモデルIDの誤り | しない |
| 409 | conflict_error | リソースの同時更新など状態の衝突 | 衝突を解消して送る |
| 413 | request_too_large | リクエストのバイト数超過 | しない |
| 429 | rate_limit_error | レート制限・加速制限・ティアの支出上限 | retry-afterがあれば送る |
| 500 | api_error | Anthropic側の予期しない内部エラー | 指数バックオフで送る |
| 504 | timeout_error | 処理中のタイムアウト | ストリーミングに切り替える |
| 529 | overloaded_error | API全体の一時的な過負荷 | 指数バックオフで送る |
413の上限はMessages APIが128MB、Batch APIが256MB、Files APIが500MBです。この413はAPIサーバーに届く前にCloudflareが返すため、request_idが付かない前提でログを設計しておくと調査で迷いません。401のうちメッセージが CORS requests are not allowed for this Organization で始まるものはキーの問題ではなく、ブラウザから直接呼んでいることが原因です。
エラー応答のJSONとrequest_idを問い合わせ用にログへ残す手順
エラー応答は必ずJSONで、最上位の error に type と message が入り、横に request_id が付きます。
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}同じ値は全レスポンスの request-id ヘッダーにも入ります。curlで再現するときは -i を付けるとヘッダーごと表示されます。
curl -sS -i https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{"model": "claude-sonnet-5-5", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}]}'Python SDKでは応答オブジェクトの _request_id で取得できます。サポートへ問い合わせるときはこのIDが調査の起点になるため、エラー時だけでなく正常時もアプリのログへ書き出す設計が必要です。公式は type の値が今後増える可能性に触れており、未知の値でも落ちない分岐にしておく必要があります。
400 invalid_request_errorのモデル世代別パラメータ拒否
400は「書き方の誤り」に見えますが、2026年は既存コードのままモデルだけを新しくして出るケースが目立ちます。公式のエラーページに載っている代表例は次の4つです。
- Claude 4.6以降に、最後がassistantのメッセージ（prefill）を送る
- Claude 4.7以降に
thinking: {"type": "enabled"}を送る（adaptiveへの移行が必要） - Opus 5.5・Sonnet 5.5・Fable 5.1に
tool_choiceのanyやtoolを送る - 使用量が自分で設定した支出上限に達した（メッセージが
You have reached your specified API usage limitsで始まる）
最後の1つだけはコードの誤りではなく、Consoleで上限を上げれば解消します。temperature を外す書き換えなど、APIバージョン2026-10-21で増えた400はClaude API 2026-10-21移行ガイドで扱っています。廃止済みモデルを呼んで失敗している場合は、Claude APIのモデルID一覧で現行のIDを確かめてください。
429の組織上限と529の全体混雑を応答内容で見分ける確認手順
429のerror.typeはrate_limit_error、529はoverloaded_errorです。どちらも「混んでいる」ように見えますが、429は自分の組織の上限、529はAnthropic側の全体の混雑です。待つべき時間も、取れる対策も異なります。
429はRPM・ITPM・OTPMの超過でretry-afterの秒数だけ待てば通る
公式のRate limitsによると、Messages APIの制限はモデルごとの毎分リクエスト数（RPM）・入力トークン数（ITPM）・出力トークン数（OTPM）で測られます。たとえばStartティアのClaude Opus 5.5は4,000 RPM・200万ITPM・40万OTPMです。
方式はトークンバケットで、上限まで連続的に回復します。60 RPMが「1秒に1件」として適用されることもあり、1分の合計が上限内でも短い集中で429になります。応答に retry-after があれば、送り直すタイミングは指定された秒数の経過後です。それより早く送ると失敗します。
残量は anthropic-ratelimit-requests-remaining や anthropic-ratelimit-input-tokens-remaining などのヘッダーで分かります。ITPMに数えられるのはキャッシュされていない入力だけなので、プロンプトキャッシュの読み込み分は上限を消費しません。使用量が急に増えたときに出る「加速制限」の429もあり、公式は流量を段階的に上げるよう案内しています。
retry-afterの無い429と利用ティアの月間支出上限の判別基準
Start・Build・Scaleの各ティアには月間支出上限があり、それぞれ500ドル・1,000ドル・200,000ドルです。上限に達すると、翌月1日の00:00 UTCまでAPIが止まり、すべてのリクエストが429を返します。
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "You have reached your API usage limits: ...",
"details": { "error_code": "enforced_spend_limit_reached" }
},
"request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}error.type は通常のレート制限と同じ rate_limit_error ですが、retry-after ヘッダーが付きません。公式はSDKの自動リトライを含め、アクセスが戻るまで再試行は失敗し続けると明記しています。ティアの上げ方と月額の考え方はAnthropic API（Claude API）の料金とAPIキー取得方法に、2026年6月のティア再編の経緯はClaude Code利用上限2倍化とその後にまとめています。
529の全体混雑とstatus.claude.comの障害告知の照合
529 overloaded_error は、全利用者のトラフィックが集中してAPIが一時的に過負荷になった状態です。自分のリクエスト量とは関係がないため、上限の引き上げを申請しても防げません。
529が数分続くときは、公式ステータスページ status.claude.comを確認します。コンポーネントは claude.ai、Claude Console、Claude API（api.anthropic.com）、Claude Code などに分かれており、APIだけを見るなら「Claude API」の行です。メール・Slack・Microsoft Teams・Webhookでの購読や、Atom・RSSのフィードも用意されています。
監視に組み込むなら、components.jsonを取得して該当コンポーネントの状態を読みます。2026年11月7日時点では全コンポーネントが operational でした。
import json
import urllib.request
URL = "https://status.claude.com/api/v2/components.json"
with urllib.request.urlopen(URL, timeout=10) as r:
data = json.load(r)
for c in data["components"]:
if c["name"].startswith("Claude API"):
# operational 以外なら障害か性能低下が告知されている
print(c["name"], c["status"])ステータスページが平常のまま529が続く場合でも、特定モデルだけが混んでいることがあります。2026年10月24〜27日にはSonnet 5.5やFable 5.1など、モデル単位のエラーが個別に告知されていました。
Python SDKの自動リトライ設定と指数バックオフを自前で組むコード
Python SDKのドキュメントでは、接続エラー・408・409・429・500以上を既定で2回まで、短い指数バックオフで再試行すると説明されています。SDKはPython 3.10以上が必要で、APIバージョン2026-10-21を使うのはSDK 2.0.0からです。
SDK既定の2回リトライとmax_retries・timeoutを用途別に変える設定
回数は max_retries、待ち時間の上限は timeout（既定10分）で変えます。クライアント全体の既定値と、リクエスト単位の上書きの両方が使えます。
import anthropic
# 画面から呼ぶ対話用：待たせないよう回数と時間を絞る
chat_client = anthropic.Anthropic(max_retries=1, timeout=30.0)
# 夜間バッチ用：回数を増やして一時的な529を吸収する
batch_client = anthropic.Anthropic(max_retries=5)
# リクエスト単位で上書きする
msg = chat_client.with_options(max_retries=3).messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(msg._request_id)SDKの例外はステータスごとに分かれており、429は RateLimitError、500以上は InternalServerError、接続できないときは APIConnectionError、タイムアウトは APITimeoutError です。公式は、メッセージ文字列の一致ではなく型で捕まえ、具体的な型から順に書くよう案内しています。
retry-afterを優先し指数バックオフとジッターで再送する関数の実装
SDKの自動リトライは手軽ですが、支出上限の429も区別せずに再試行し、待ち時間のログも残りません。本番では max_retries=0 にして、次のような関数で判定を一元化します。
import random
import time
import anthropic
client = anthropic.Anthropic(max_retries=0) # SDK側の再試行を切り、ここで管理する
RETRYABLE = {408, 409, 429, 500, 502, 503, 504, 529}
def error_code(e):
body = e.body if isinstance(e.body, dict) else {}
return ((body.get("error") or {}).get("details") or {}).get("error_code")
def create_with_retry(max_attempts=6, base=1.0, cap=60.0, **params):
for attempt in range(1, max_attempts + 1):
wait = None
try:
return client.messages.create(**params)
except anthropic.APIConnectionError: # APITimeoutError もここに入る
if attempt == max_attempts:
raise
except anthropic.APIStatusError as e:
if (e.status_code not in RETRYABLE
or error_code(e) == "enforced_spend_limit_reached"
or attempt == max_attempts):
raise
try:
wait = float(e.response.headers.get("retry-after", ""))
except ValueError:
wait = None
if wait is None:
wait = random.uniform(0, min(cap, base * 2 ** (attempt - 1)))
print(f"retry {attempt}: {wait:.1f}s 待機")
time.sleep(wait)待ち時間は、retry-after があればその値を使い、無ければ1秒・2秒・4秒と倍にした上限の範囲でランダムに選びます。ランダム性（ジッター）を入れるのは、複数のワーカーが同じ秒数で一斉に再送して再び529を招くのを避けるためです。e.body などの属性はSDKのGitHubリポジトリのソースで確認できます。
ストリーミング中のerrorイベントは200応答の後に届くので別処理が必要
stream=True で受けている場合、HTTPは200で始まり、途中で次のようなイベントが届くことがあります。Streaming messagesの公式説明では、混雑時の overloaded_error は非ストリーミングなら529に相当すると書かれています。
event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}ステータスコードは200のままなので、HTTPステータスだけで成否を判定する監視では失敗として数えられません。Claude 4.6以降のモデルでは、途中まで受け取った本文をuserメッセージに入れ、続きから書くよう指示して再開する方法が公式に示されています。tool_useとthinkingのブロックは途中から復元できないため、その場合はリクエストごと送り直します。
Claude Codeに出るAPI Errorの表示と再試行回数を変える環境変数
Claude CodeもClaude APIを呼んでいるため、同じ種類のエラーが画面に出ます。違いは、表示の前にClaude Code自身が再試行している点です。
Repeated 529 Overloadedと500の表示文言と既定10回の自動再試行
Claude Codeのエラーリファレンスによると、一時的な障害は指数バックオフで最大10回再試行され、それでも失敗したときに次のような表示になります。
API Error: Repeated 529 Overloaded errors. The API is at capacity ...API Error: 500 Internal server error. This is a server-side issue, usually temporary ...
529は利用上限ではなく、クォータにも数えられません。数分待って再実行するか、/model で別のモデルに切り替えれば作業を続けられます。You've hit your session limit のようにリセット時刻が表示されるものはプランの利用上限で、APIのエラーとは別物です。ログインやAPIキーの認証で止まる場合はClaude Codeのログイン方法と認証エラーの直し方を参照してください。
Claude Codeの無人実行で使う再試行回数とウォッチドッグの設定例
CIや夜間の自動実行では、10回で諦めずに待ち続けたほうが都合のよい場面があります。公式の環境変数で次のように変えられます。
# 429・529の容量エラーを回数の上限後も待ち続ける（無人実行向け）
export CLAUDE_CODE_RETRY_WATCHDOG=1
# 529再試行の初回待ちを2秒に延ばす（既定500ミリ秒・上限32000）
export CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=2000
# 低速なプロキシ経由でヘッダー受信までの制限を15分に延ばす（既定600000）
export API_TIMEOUT_MS=900000再試行回数そのものは CLAUDE_CODE_MAX_RETRIES（既定10）で変えられます。ウォッチドッグは対話中の利用では採用しません。混雑が長引くと画面が戻らなくなるため、人が見ている場面では既定の10回で失敗させ、モデルを切り替えたほうが早く進みます。
本番システムでリトライを止める条件とフォールバックを採用する判断
ここまでの仕様を踏まえ、業務システムに組み込むときの判断を言い切ります。再試行は「通る見込みのあるものだけ」に絞り、残りは早く人に知らせます。
400・401・403・413と支出上限の429は再試行せず即通知に回す理由
400・401・402・403・404・413は、同じリクエストを何度送っても結果が変わりません。再試行すると失敗までの時間が延び、利用者を長く待たせるだけです。支出上限の429も同じで、SDK既定の2回の再試行は翌月まで続く停止を数秒遅らせる効果しかありません。
これらは発生した時点でrequest_idと error.message を添えて運用担当へ通知します。特に401は、キーの失効や漏えいによる無効化の可能性があるため、自動で別のキーへ切り替える実装は採用しません。原因を確かめずに切り替えると、漏えいの調査が遅れます。
529が続くときに別モデル・別経路へ切り替える条件と見送る場面
529が数分以上続き、処理を止められない業務（問い合わせの一次回答や受注データの分類など）であれば、フォールバックを採用します。切り替え先は2通りあります。
- 同じClaude APIの別モデルに切り替える（例：Sonnet 5.5からHaiku 5.5）
- Amazon Bedrockなど別の提供経路で同じモデルを呼ぶ
1は実装が簡単ですが、モデルを替えると単価と出力の傾向が変わり、受け付けるパラメータも異なります。2は品質を保てる一方、BedrockはモデルIDの書式と認証が異なるため、Bedrock Claudeの使い方で確認したモデルIDの書式と認証の設定を、切り替え前に用意しておくことが必要です。複数の経路をまとめて切り替えるなら、LiteLLMのフォールバック設定のようにProxyで吸収する構成も選べます。
反対に、数時間遅れても困らない集計やレポート生成では、フォールバックは過剰です。指数バックオフで待つか、Message Batches APIに回せば十分です。どこまで止められないかの線引きや、再試行と監視を含めた本番設計を社内で組みにくい場合は、生成AI導入支援としてご相談を受けています。
Claude APIのエラー対処と障害状況の確認方法でよくある質問
Claude APIのエラー対応について、実装と運用でよく出る疑問をまとめました。
Claude APIの529エラーはどれくらいで解消しますか？
公式ドキュメントは解消までの目安時間を示していません。529は全利用者のトラフィック集中による一時的な過負荷で、自分の側でできるのは指数バックオフでの再試行と、status.claude.comでの告知の確認です。数分以上続き、ステータスページにClaude APIやモデル単位のエラーが告知されている場合は、別モデルや別経路への切り替えを検討します。
429エラーが出たら利用ティアを上げるべきですか？
まず retry-after ヘッダーと error.details.error_code を確認します。retry-afterがあるならRPM・ITPM・OTPMの一時的な超過で、待てば通ります。プロンプトキャッシュの読み込みはITPMに数えられないため、キャッシュの導入も一時的な超過への対処方法です。retry-afterが無く enforced_spend_limit_reached なら月間支出上限で、ConsoleのRate limitsページからティアの引き上げを申請します。
Claude APIの障害状況はどこで確認できますか？
公式のステータスページ status.claude.com で確認できます。claude.ai・Claude Console・Claude API・Claude Codeなどがコンポーネント別に表示され、過去のインシデントの履歴も閲覧可能です。メール・Slack・Webhookなどで通知を受け取れるほか、/api/v2/components.json を取得すれば監視ツールから状態を読み取れます。
Claude APIの401エラーはAPIキーを作り直せば直りますか？
キーの形式誤り・失効・期限切れが原因なら、Consoleで発行し直したキーに差し替えれば直ります。ただし、メッセージが CORS requests are not allowed for this Organization で始まる401はキーの問題ではありません。ブラウザから直接APIを呼んでいることが原因で、自社のサーバー側から呼ぶ構成に変える必要があります。キーを作り直しても解消しません。
Claude APIのエラーでも料金はかかりますか？
公式のエラーページには、エラー応答の課金についての記載はありません。料金は応答に含まれる usage の入力・出力トークン数で計算されるため、正常に返った応答のusageを記録し、ConsoleのUsageページの値と突き合わせて確認するのが確実です。なお、Claude Codeの529はクォータに数えられないと公式に明記されています。
関連記事
- Anthropic API（Claude API）の料金とAPIキー取得方法：利用ティアと月間支出上限、APIキーの発行と無効化の手順を確認できます。
- Claude API 2026-10-21移行ガイド：APIバージョンを上げたときに400になる箇所と書き換えコードを扱っています。
- Claude APIのモデルID一覧：廃止済みモデルを呼んで失敗していないか、Models APIで確かめる手順を解説しています。
- Claude Codeのログイン方法：Claude Codeの認証エラーと、サブスクとAPIキーの切り替えを扱っています。
- LiteLLMとは：複数のLLMをまとめて呼び、障害時に別モデルへ切り替えるProxyの構築手順を確認できます。
