Claude API エラー — Rate Limit、400、500、529 の原因と修正

Claude API を使っている開発者なら、どこかのタイミングで必ずエラーに遭遇します。原因が自分の request 形式にある場合もあれば、Anthropic 側の server issue の場合もあります。また、Claude Code や agentic workflow のように高頻度・大容量で使う構成では、rate limit などアーキテクチャ上の制約にぶつかることもあります。このガイドでは、Claude API でよく出る error code を、実際の原因、具体的な修正方法、本番運用で使える retry logic とあわせて整理します。さらに、AI Prime Tech Unlimited のような複数 upstream account を持つ gateway 経由で routing することで、rate-limit や overload 系のエラー頻度をどう下げられるかも解説します。claude api 購入を検討している方、claude api キーの運用に悩んでいる方、claude 無制限に近い使い勝手を求めている方にも役立つ内容です。

Error 400 — Bad Request

400 error は、request の構造や内容が Claude API の仕様に合っていないことを意味します。つまり API は response を生成しようとする前の段階で request を拒否しています。まず確認すべきなのは error body です。そこには何が間違っているのかを示す message が入っているため、必ず丁寧に読みます。よくある原因としては、messages array が空、または形式が壊れている、content field が string ではなく null になっている、max_tokens が model の上限を超えている、存在しない model identifier を指定している、system prompt の形式が API 仕様と違う、tool definitions の JSON schema に誤りがある、といったものがあります。400 は一時的な障害ではなく、基本的には request を直さない限り再送しても成功しません。そのため、retry logic で何度も投げ直すより、validation と error message の確認を優先するのが正しい対応です。

Claude Code ユーザーが最もよく遭遇する 400 error のひとつが、context length exceeded です。会話履歴、読み込んだ file、tool output、subagent の結果などが積み上がり、model の context window を超えると、API は input が長すぎるという内容の 400 を返します。多くの Claude model では 200K tokens 前後の大きな context を扱えますが、それでも巨大な repository や長時間の coding session では簡単に上限に到達します。この場合の修正方法は、Claude Code で /compact を使って履歴を要約する、不要な large file contents を context から外す、長い log や build output を削る、または新しい session を開始することです。これは rate limit ではありません。単位時間あたりの利用量ではなく、単一 request のサイズに対するハードな制約です。claude 無制限プランのような gateway を使っていても、model 自体の context window を超える request は成功しない点に注意してください。

もうひとつ多い 400 は、未対応 parameter や間違った model version を送っているケースです。SDK を更新した直後、model identifier を新しいものに変えた直後、あるいは別 provider 向けの request payload を流用した場合に起きやすいです。Claude API の model IDs は case-sensitive で、version-specific です。たとえば 'claude-opus-4-6' が有効でも、'Claude-Opus-4.6' のような表記は無効です。また、古い SDK では認識されない field、新しい API では廃止された field、tool use の schema 定義ミスなども 400 の原因になります。迷ったら /v1/models endpoint を叩いて、provider が受け付ける正確な identifier を確認してください。AI Prime Tech Unlimited 経由で claude api キーを設定している場合も、base_url が gateway になっているだけで、request payload の妥当性チェックは必要です。claude code api キー設定を行った後に 400 が出る場合は、API key よりも request body、model 名、context size を先に疑うのが効率的です。

Error 429 — Rate Limit Reached

429 は、許可された request rate を超えたことを示します。response には通常 Retry-After header が含まれており、何秒待ってから retry すべきかが示されます。Anthropic の rate limit は単純な request count だけではありません。requests per minute、つまり RPM、tokens per minute、つまり TPM、tokens per day、つまり TPD など、複数の軸で制限されています。このどれかひとつでも上限に達すると 429 が返ります。error message には、どの limit に当たったのかが書かれていることが多いため、429 を見たら status code だけでなく message と header を確認してください。特に Claude Code のように短時間で多数の tool call を発行する使い方では、RPM に当たる場合もあれば、巨大な file を context に入れて TPM を使い切る場合もあります。

Claude Code ユーザーにとって rate limit は非常にストレスの大きいエラーです。coding の流れを止めるだけでなく、subagent が並列で動いている途中、複数 file を読ませた直後、test failure の解析中など、ちょうど集中しているタイミングで発生しがちだからです。1人の developer が使っているだけでも、Claude Code の subagents、parallel operations、large context session によって、低い tier の account ではすぐに limit に達します。Anthropic direct の claude api 料金や tier は利用量に応じて変わりますが、低 tier では heavy agentic usage に対して RPM や TPM が厳しく感じられることがあります。そのため、claude api 購入を検討する段階で、単に token 単価だけでなく、実際にどれくらい安定して使えるか、rate limit にどれくらい余裕があるかを見ることが重要です。

429 に対する正しい対応は、exponential backoff と jitter です。Retry-After がある場合はまずその秒数を尊重し、そのうえで randomized delay を加えることで、複数 client が同時に retry してまた同時に失敗する thundering herd を避けます。たとえば 1秒、2秒、4秒、8秒と待ち時間を増やしつつ、0.5〜1.5 倍程度の random factor を掛けます。AI Prime Tech Unlimited のような gateway は、複数 upstream accounts に request を分散することで 429 の頻度を下げられます。単一 account の rate-limit budget ではなく、複数 account の合算に近い余力を使えるためです。ある upstream account が rate-limited になった場合、gateway は別の upstream account に routing できます。もちろん fair-use や gateway 側の制御はありますが、Claude Code を長時間使う開発者にとって、直接 1 account に投げるより安定しやすい構成です。

Error 500 — Internal Server Error

500 error は、server side で何か問題が発生したことを意味します。これは request の書き方が悪いわけではなく、基本的にはあなたが prompt や JSON を修正して解決するタイプのエラーではありません。Anthropic 側の infrastructure、internal service、deployment、capacity change、依存 service の不調などで一時的に発生します。重要なのは、500 は多くの場合 transient、つまり一時的であるという点です。同じ request が 500 で失敗しても、少し待ってからまったく同じ内容で retry すると成功することがよくあります。400 のように構造的に invalid な request とは扱いを分ける必要があります。

500 error の handling は比較的シンプルです。1〜2秒待って同じ request を retry し、それでも失敗する場合は 4秒、8秒、16秒というように exponential backoff で待ち時間を伸ばします。上限は多くの application では 60秒程度で十分です。多くの 500 は最初の retry で解消しますが、数分以上継続する場合は、Anthropic の status page や gateway の status endpoint を確認してください。本番環境では、retry count、最終的な failure、request id、model、latency を log に残しておくと原因切り分けがしやすくなります。AI Prime Tech Unlimited の gateway を使っている場合、gateway 側で upstream retry が行われ、client からは少し response が遅くなっただけに見えることもあります。

500 が返ったときにやってはいけないのは、原因を自分の prompt や context にあると決めつけて無駄に変更することです。prompt を短くする、model を変える、tool schema を削る、context を減らすといった対応は、400 や context length issue には有効ですが、500 の本質的な解決にはなりません。もちろん巨大 request が infrastructure に負荷をかけている可能性はゼロではありませんが、status code の意味としては server-side error です。実務では、500 は retry、429 は Retry-After と backoff、400 は request 修正、というように分類して扱うと混乱が減ります。5〜10分以上連続して 500 が続く場合は alert を出し、provider status を確認し、必要に応じて fallback provider や gateway route の状態を確認するのが安全です。

Error 529 — Overloaded (overloaded_error)

529 status code は Anthropic 固有に近い扱いの error で、API が high demand の状態にあり、指定した model が一時的に capacity に達していることを示します。429 はあなたの rate limit を超えたという意味ですが、529 は system 全体、または該当 model の処理 capacity が混雑しているという意味です。つまり、自分の RPM や TPM を超えていなくても 529 は起きます。あなたの request が悪いわけでも、claude api キーが無効なわけでもありません。その瞬間に available compute より demand が多いだけです。error body には overloaded_error のような type が含まれることがあります。

529 は peak hours、特に US business hours に増えやすい傾向があります。また、新 model release の直後は多くのユーザーが同時に test するため、capacity pressure が高まりやすくなります。SNS や開発者コミュニティで話題になったタイミング、benchmark が共有された直後、大規模 customer の traffic が急増した時間帯などにも起きやすいです。model によっても差があります。一般的に Opus は request あたりの compute cost が高く、capacity constraint が厳しくなりやすいため、Sonnet や Haiku よりも overloaded の影響を受けやすいことがあります。production workload で高い可用性が必要な場合、常に最高性能 model だけに依存する設計は避け、fallback strategy を用意しておくと安定します。

529 には 500 より長めの backoff を使うのが実践的です。最初から 5〜10秒待ち、失敗が続く場合は exponential に待ち時間を伸ばします。chat UI のように user が待てる場合は message を出して再試行し、batch job のように時間に余裕がある場合は queue に戻す設計も有効です。本番 system では model fallback も検討してください。たとえば Opus が 529 を返した場合、その request だけ Sonnet に切り替える、または低優先度 task は later retry に回すといった設計です。AI Prime Tech Unlimited のような gateway は、複数 upstream account と routing option を持つため、overload 時にも別 account 経由で成功する可能性があります。account ごとの priority tier や queue position が異なる場合、gateway がより空いている route を選べるため、直接接続より 529 の体感頻度を下げられることがあります。

Production-Ready Retry Logic

本番運用に耐える retry logic は、transient errors と permanent errors を明確に分けます。429、500、529 は基本的に retryable として扱い、exponential backoff と jitter を使います。一方、400、401、403 は多くの場合 non-retryable です。400 は request が invalid、401 は authentication、つまり API key や header の問題、403 は権限や policy の問題であることが多いため、同じ request をただ再送しても成功しません。基本パターンは、request を実行し、status code を確認し、retryable なら backoff して最大 N 回まで再試行し、non-retryable なら即座に例外を投げる、というものです。多くの application では max retries は 3〜5 回で十分です。

jitter は retry を安定させるうえで非常に重要です。たとえば 10個の client が同時に rate limit に当たり、全員がぴったり 2秒後に retry したら、また同じ瞬間に traffic が集中して再び失敗する可能性があります。delay に random factor を掛けて retry timing を分散すれば、success rate は大きく改善します。実装としては、base delay に 2 の attempt 乗を掛け、さらに 0.5〜1.5 の random multiplier を掛ける方法が簡単です。Retry-After header がある 429 では、その値を下回らないようにしつつ jitter を追加するのが望ましいです。Claude API client を自作している場合も、SDK を使っている場合も、この設計を HTTP client level に入れておくと、すべての API call が自動的に恩恵を受けます。

Claude Code や agentic workflow では、retry を個別の command や tool call ごとに手作業で入れるのではなく、HTTP client layer、SDK wrapper、gateway layer のいずれかで共通化するのがおすすめです。subagent、file analysis、test generation、refactor plan などは内部的に複数 request を投げるため、低レベルで retry が効くほど体感が安定します。Anthropic SDK には基本的な retry logic が含まれていますが、timeout、max retries、backoff の上限、log 出力、idempotency の扱いは use case に合わせて調整したい場面があります。AI Prime Tech Unlimited を使う場合、gateway が upstream retry と routing を内部で処理するため、client 側に到達する 429、500、529 をそもそも減らせます。claude code api キー設定では base_url と api_key を gateway に向けるだけで既存の SDK 実装を活かせることが多く、claude api 料金を定額に近い形で予測しやすくしたい開発者にも向いています。

How a Gateway Reduces These Errors

AI Prime Tech Unlimited のように適切に設計された gateway は、Claude API の error frequency を複数のレイヤーで下げます。429 rate limit に対しては、複数の upstream API accounts に request を分散し、単一 account の allocation ではなく、複数 account の合算に近い rate-limit budget を活用します。これにより、Claude Code のような高頻度 request、subagent の並列実行、大きな context を伴う coding session でも、direct account より 429 に当たりにくくなります。529 overloaded_error に対しては、別の upstream account、別の priority tier、別の queue position を試せるため、ある route が混雑していても別 route で成功する余地があります。

500 server error に対しても gateway は有効です。client に error を返す前に gateway 側で retry し、別 upstream に切り替えることで、開発者から見ると単に response が少し遅くなっただけで済むことがあります。もちろん 400 error については、request 自体が invalid なので gateway でも根本的には解決できません。messages array が壊れている、model 名が間違っている、context が長すぎるといった問題は、client 側の修正が必要です。ただし、良い gateway は raw な upstream error をそのまま返すだけでなく、debug しやすい message、request id、status 情報を返すため、原因特定の時間を短縮できます。特に claude api キーや base_url の設定ミス、認証 header の不備、model routing の問題を切り分けるときに役立ちます。

開発者にとっての実利は、application に到達する error が減り、client side の retry logic が過剰に複雑にならず、peak hours でも performance が安定しやすいことです。Claude Code の session では、task の途中で error が出るだけで思考の流れが途切れます。production application では、error rate はそのまま user experience、support cost、SLA に影響します。gateway を使うことで、rate limit、overload、server error の多くを手前で吸収できるため、開発体験も運用品質も上がります。さらに unlimited plan の flat rate であれば、retry や rerouting による追加 token cost を過度に気にせず使いやすくなります。claude api 購入時に direct billing と gateway のどちらを選ぶか迷っている場合は、単純な claude api 料金だけでなく、rate limit の余裕、Claude Code での安定性、claude 無制限に近い作業体験、チームでの API key 管理のしやすさまで含めて比較すると判断しやすくなります。

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://claudeapikey.dev",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # 400 は retry しない

# 使用例:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

FAQ

'claude api error rate limit reached' とはどういう意味ですか？
許可された requests per minute、tokens per minute、または tokens per day を超えたという意味です。API は HTTP 429 と Retry-After header を返します。指定された時間だけ待ってから retry してください。複数 upstream account を持つ gateway を使うと、より大きな rate-limit pool に request を分散できるため、このエラーを減らせます。

Claude API error 400 はどう直せばいいですか？
まず error message body を読みます。何が間違っているかが具体的に書かれています。よくある原因は、context が長すぎる場合（/compact を使う）、invalid model ID（/v1/models を確認）、壊れた messages array、未対応 parameter などです。400 は transient ではないため、request を修正せずに retry してはいけません。

529 overloaded_error とは何ですか？
529 は、指定した model に対して Anthropic の infrastructure が capacity 上限に近い、または超えていることを意味します。これは system-wide overload であり、あなた個人の rate limit ではありません。5〜10秒待って exponential backoff で retry してください。peak hours には Opus から Sonnet へ fallback する設計も有効です。

unlimited plan を使えば rate limit error は完全になくなりますか？
大幅に減ります。gateway が複数 upstream account に routing するため、利用可能な rate limit が実質的に増えるからです。ただし gateway 側の fair-use rate limit はあります。単一の direct Anthropic account より、特に Claude Code を頻繁に使う場合は 429 error がかなり少なくなります。

error 500 は retry すべきですか？
はい。500 は一時的な server-side issue です。1〜2秒待って、まったく同じ request を exponential backoff 付きで retry してください。request を変更する必要はありません。原因は input ではないためです。5分以上 500 が続く場合は provider の status page を確認してください。