Claude API Internal Server Error の直し方：500 api_error を先に切り分ける

Claude API が API Error: 500 を返し、error.type が api_error、message が Internal server error なら、まず「API から返ってきたサーバー側エラー」として扱います。API key、請求、prompt、アカウント、ブラウザ cache が壊れた証拠として扱うのは早すぎます。

最初の 1 分でやることは小さく固定します。現在の Claude Status を確認し、error body と request_id、または response header の request-id を保存し、短い上限付き jitter retry だけを行います。この段階では model、endpoint、認証経路、SDK または gateway 経路、request body を変えません。

Status は日時付きの手掛かりです。この実行では 2026-05-02T13:51Z に Claude Status を確認し、公開 status API は all systems operational を返しました。ただし直近の resolved incidents には API や model-specific elevated-error の記録が残っていました。緑の status は live incident の可能性を狭めますが、自分の model、account route、SDK、gateway、request shape が復旧した証明にはなりません。

60 秒の分岐ボード

key を交換したり、prompt を大きく書き換えたり、billing を疑ったり、provider を切り替えたりする前に、この分岐を確認します。HTTP status、error body、request id があるなら、少なくとも API 層から応答が返っています。status も body も request id もない connection failure とは別の問題です。

このエラーの復旧範囲は狭いです。きれいな Claude API Internal Server Error は 500 api_error の回復分岐です。一時的に直ることもありますし、特定の model path、account route、request shape だけで繰り返すこともあります。重要なのは、直しながら証拠を壊さないことです。

Claude API における 500 api_error の意味

Anthropic の API error reference では、HTTP 500 は api_error と定義されています。同じ表で 429 rate_limit_error、504 timeout_error、529 overloaded_error は別の型として扱われます。error response には error.type、error.message、request_id が含まれ、API response には request-id header も付きます。

この公式分類が recovery boundary になります。返却済みの 500 api_error は予期しない内部 API 失敗であり、通常の account-state message ではありません。billing が空、key が期限切れ、prompt が不正、browser cache が壊れている、という判断を最初に置くべきではありません。それらはそれぞれ別のシグナルを持ちます。

request_id の扱いは特に重要です。画面に出た Internal server error の screenshot は人間向けには便利ですが、support や platform team が具体的な API call を追うためには request identifier が必要です。SDK が header を公開しているなら request-id を保存します。JSON body に request_id があるなら保存します。どちらもないなら、返却済み API error ではなく connection 分岐の可能性があります。

500 と 529 は混ぜないでください。どちらも Anthropic 側の揺れに見えることがありますが、client behavior は違います。529 は過負荷なので pressure reduction、queue、cooldown、retry storm の防止が中心です。500 は status 確認、短い retry、identifier 保存、同じ経路での再現確認が中心です。

500 と 504 も違います。504 は request duration、idle drop、streaming、batch 化の問題を示します。長い処理なら streaming や Message Batches を考えるべきです。正確な型が timeout_error なら、Internal Server Error と呼び続けず、request shape を意図的に変えて検証します。

安全な recovery loop

Claude API 500 の回復手順は地味であるほど良いです。まず Claude Status を見て時刻を記録します。次に error body、headers、request_id を保存します。その後、その仕事が安全に繰り返せるかを判断します。read-only の呼び出し、内部 batch item、ユーザーへの副作用を持つ workflow では retry の許容範囲が違います。

retry する場合は budget を使います。attempt 数、合計時間、jitter、stop condition を決めます。ユーザーが待っている chat turn は数秒の 1、2 回が限界かもしれません。background batch はもっと待てます。購入、作成、通知など副作用が絡む処理では caller-side deduplication なしに retry しないほうが安全です。

検証では経路を固定します。同じ model、同じ endpoint、同じ auth owner、同じ SDK または gateway、同じ request body、同じ timeout class を保ちます。この制約は根性論ではありません。同じ path が短時間で復旧したのか、別の path に移っただけなのかを区別するためです。

Status に active API incident がある場合、ローカルの変数を触り続けないでください。non-urgent work を止め、background jobs を queue に入れ、incident が更新された後で同じ path を再確認します。incident の最中に model、prompt、key、gateway、timeout を全部変えると、復旧後に何が効いたか分からなくなります。

Status が green でも、短い retry は有効です。ただし budget 後も同じ path が 500 api_error を返すなら停止します。そこから先は random change ではなく escalation packet の段階です。gateway への切り替えが必要な本番事情がある場合も、まず元の失敗証拠を保存し、route comparison として記録します。

本番環境の 500 制御

手作業の triage は 1 回の障害には効きます。本番では、同じ考え方をログ、retry、circuit breaker、degraded mode に入れておく必要があります。

retry は open-ended にしません。attempt 数、elapsed time、concurrency を制限し、jitter を入れます。ログには retry count、backoff window、final result を残します。後から見て、retry で回復した transient error なのか、同じ経路で持続した 500 なのかが分かる状態にします。

idempotent work と non-idempotent work を分けます。read-only classification、内部 batch、ユーザーが見る作成処理、支払いに近い処理を同じ retry policy にしないでください。server error は downstream が何もしていないことを保証しません。job id、request key、business deduplication を使ってから retry を許可します。

同じ route で 500 api_error が一定数を超えたら circuit breaker を使います。非緊急呼び出しを止め、queue に逃がし、UI には controlled degraded state を出します。再開時は小さな same-path probe で復旧を確認してから徐々に戻します。これにより、短い API 側の揺れを自分の retry storm で大きくしません。

ログは分岐を判断できる粒度にします。HTTP status、error.type、error.message、request_id または request-id、model、endpoint、SDK version、auth route、gateway route、request size class、retry count、timestamp が最低限です。API key、顧客データ、private prompt、proxy log、環境変数 dump は保存しません。

model switching は診断の第一手ではなく product decision です。特定 model path だけが 500 を返し、別 model がユーザー仕事を満たせるなら一時的な fallback はあり得ます。ただし degraded routing と明示し、元の path の証拠を残し、後で回復を検証します。

表面と route owner を分ける

Claude API Internal Server Error という言葉は混在環境で使われがちです。direct API、Claude Code、SDK exception、gateway、timeout、no-response connection failure は、ログの見た目だけでは似て見えます。

見えている表面が Claude Code なら、Claude Code 分岐に進みます。Claude Code は Claude API を呼びますが、terminal には login state、resumed session、OAuth と API key の owner、shell proxy、環境変数、command diagnostics が重なります。terminal の 500 は Claude Code API Error 500 から確認します。500、529、429 が混ざるなら Claude Code 500/529/rate-limit router が適切です。

SDK exception なら、returned API status か connection exception かを分けます。status 500、headers、error body があるなら returned-error branch です。HTTP status がない APIConnectionError 系なら no-response branch です。その場合は Claude API connection error で request ID 境界から確認します。

gateway または provider route なら、推測ではなく比較します。同じ prompt、model intent、input size、timeout class、runtime を direct Anthropic と gateway で比べます。direct が成功し gateway が失敗するなら、route mapping、provider capacity、credential owner、proxy behavior、compatibility が候補です。両方が 500 なら広い信号ですが、それでも元の request identifier が必要です。

exact error が変わったら branch も変えます。529 overloaded_error は過負荷、429 rate_limit_error は限流と credential route、504 timeout_error は request duration、response なしは network、proxy、TLS、SDK timeout、route owner です。出口を明確にするほど、読者は「とりあえず再試行」を減らせます。

escalation packet

エスカレーションは小さな loop が終わった後です。status を確認した、request evidence を保存した、retry は上限付きだった、同じ path がまだ 500 api_error を返す。この条件がそろったら、random change より evidence packet の価値が高くなります。

packet には、exact HTTP status と error type、request_id を含む error body または request-id header、各 attempt の timestamp と timezone、model、endpoint、SDK、SDK version、runtime、direct Anthropic/gateway/proxy/provider route owner、auth owner、request size class、streaming かどうか、retry count、backoff window、jitter behavior、final result、当時の Claude Status、最小の redacted reproduction、business impact を入れます。

secret は入れません。API key、customer data、private prompt、proxy full log、unredacted env dump は不要です。よい packet は branch と trace handle を明確にします。悪い packet は support にノイズを渡し、データ漏えいリスクを増やします。

同一経路の証拠は escalation で効きます。「500 が出たので provider を変えたら動いた」は弱い証拠です。「2026-05-02T13:51Z 時点で status green、同じ model と endpoint が 40 秒の jitter budget で 3 回 500 api_error、request ids 付き」は行動しやすい証拠です。

FAQ

Claude API Internal Server Error は 529 overload と同じですか？

同じではありません。Anthropic は HTTP 500 を api_error、529 を overloaded_error と分けています。500 は returned server-side error handling、529 は pressure reduction と retry storm 防止です。

Claude Status が緑ならローカル問題ですか？

断定できません。緑の status は公開コンポーネントの日時付きシグナルです。自分の model、endpoint、account route、region、SDK、gateway、request shape が復旧している証明ではありません。

最初に API key を交換すべきですか？

いいえ。きれいな 500 api_error は key rotation の根拠ではありません。auth、key ownership、leakage、route mismatch の証拠があるときだけ credential を扱います。

retry は何回まで安全ですか？

固定回数ではなく budget を決めます。attempt または elapsed time を制限し、jitter を入れ、安全に繰り返せる work だけを retry します。副作用のある work は deduplication が先です。

Claude Code で出た場合はどうしますか？

Claude Code 分岐です。terminal には login state、session state、OAuth/API-key routing、shell proxy variables、command diagnostics が重なります。まず /status と Claude Code API Error 500 を確認します。

support に何を送るべきですか？

HTTP status、error.type、error.message、request_id または request-id、timestamp、model、endpoint、SDK version、route owner、retry timeline、status result、redacted reproduction を送ります。短く、500 分岐が分かる形にします。

運用ルール

Claude API Internal Server Error は 500 api_error の recovery branch です。key、billing、prompt、provider を慌てて変える理由ではありません。live status を確認し、request identifier を保存し、短い jittered retry を行い、同じ path で検証し、まだ失敗する場合だけ証拠付きでエスカレーションします。