Claude API のエラーは HTTP ステータスコードとエラー型の組み合わせで返ります。どのコードが再試行すべきもので、どれがコードを直さないと直らないものかを分けておくと、無駄なリトライとサポートへの往復が減ります。ここでは公式ドキュメントの Errors に基づいて、コードの一覧・レスポンスの形・request ID の取り出し方・長時間リクエストの扱いを整理します。
HTTP エラーコードの一覧
API は予測可能な形式でエラーコードを返します。
| コード | 型 | 意味 |
|---|---|---|
| 400 | invalid_request_error | リクエストの形式か内容に問題がある。この節に無い他の 4XX にも使われることがある |
| 401 | authentication_error | API キーの問題（不正な形式・失効・期限切れ） |
| 402 | billing_error | 請求または支払い情報の問題 |
| 403 | permission_error | API キーに当該リソースを使う権限がない |
| 404 | not_found_error | リソースが見つからない。エンドポイントのパスと ID を確認する |
| 409 | conflict_error | リソースの現在の状態と衝突している。解消してから再送する |
| 413 | request_too_large | リクエストが最大バイト数を超えた |
| 429 | rate_limit_error | レート制限に当たった |
| 500 | api_error | Anthropic 側の想定外のエラー。指数バックオフで再試行する |
| 504 | timeout_error | 処理中にタイムアウトした |
| 529 | overloaded_error | API が一時的に過負荷 |
再試行の扱いで押さえておくべき点が2つあります。1つ目、公式 SDK は一時的な失敗（接続エラー・レート制限・5xx）を既定で2回まで指数バックオフで自動再試行し、retry-after があればそれに従います。各 SDK のクライアントは最大リトライ回数のオプションを持つので、設定変更も無効化もできます。
2つ目、529 は全ユーザー横断の高トラフィックでも起こります。ただし、自分の組織の利用が急増したときには加速制限によって 429 が出ることがあります。529 が続くときと 429 が続くときで疑うべき原因が違うので、混同しないでください。
ストリーミングには別の経路があります。SSE でストリーミング応答を受けている場合、API が 200 を返したあとにエラーが発生することがあります。この場合は上記の標準的な仕組みには乗りません。ストリーム中のエラーの形は公式の Error events を参照してください。
リクエストサイズの上限
リクエストのサイズには上限があり、超えると 413 request_too_large になります。
| エンドポイント | 最大リクエストサイズ |
|---|---|
| Messages API | 32 MB |
| Token Counting API | 32 MB |
| Batch API | 256 MB |
| Files API | 500 MB |
デバッグのときに知っておくと役立つ挙動があります。直接 Claude API を使っている場合、このエラーは Cloudflare が返すため、リクエストは API サーバーに到達していません。つまりサーバー側のログには残りません。「送ったのに記録が無い」ときはサイズ超過を疑ってください。
画像や PDF を base64 でインラインに埋めていると 32 MB は意外に早く到達します。大きなファイルは Files API に上げて参照する形に変えると、この上限を避けられます。
エラーレスポンスの形
エラーは常に JSON で返り、トップレベルに error オブジェクトがあります。error は必ず type と message を含み、レスポンス全体には追跡用の request_id が入ります。
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}バージョニング方針に従い、これらのオブジェクトの中身は拡張されることがあり、type の値も今後増える可能性があります。したがって、既知の type を網羅した switch を書いて既定分岐を用意しない実装は、いずれ壊れます。未知の型に落ちたときの扱いを必ず決めておいてください。
SDK の例外型
公式 SDK は生の JSON を返すのではなく、型付きの例外を送出します。クラス名と名前空間は言語ごとに違います。たとえば 404 は、Python では anthropic.NotFoundError、Ruby では Anthropic::Errors::NotFoundError、Java では com.anthropic.errors.NotFoundException になります。Go だけは例外ではなく単一の *anthropic.Error 値で返るので、StatusCode で分岐します。
実装の指針は公式が明記しています。エラーメッセージの文字列一致ではなく、SDK の型付きクラスを捕捉してください。そしてより具体的なクラスを先に処理します。メッセージ文字列は前触れなく変わり得るのに対し、型は API のバージョニング方針の下にあります。
各 SDK の完全な例外階層は、Python・TypeScript・C#・Go・Java・PHP・Ruby それぞれのページに記載されています。
request ID を取り出す
すべての API レスポンスには一意の request-id ヘッダが付きます。値は req_018EeWyXxfu5pfWkrYcMdjWG のような形です。同じ識別子はエラーレスポンス本文の request_id フィールドにも現れます。特定のリクエストについてサポートに問い合わせるときは、この ID を必ず添えてください。
cURL では次のようにヘッダだけを取り出せます。
curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}]
}'SDK からの取り出し方は言語で分かれます。Python と TypeScript はトップレベルのレスポンスオブジェクトに _request_id プロパティを持ちます。
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")C#・Go・Java・PHP は raw レスポンスのアクセサ経由、Ruby はミドルウェア経由で取得します。同じ仕組み（Python の with_raw_response、TypeScript の .withResponse() を含む）で、anthropic-organization-id や anthropic-workspace-id といった他のレスポンスヘッダも読めます。
Claude Platform on AWS では request ID が2つ返ります。AWS のリクエスト ID（x-amzn-requestid。主。CloudTrail に索引される）と Anthropic のリクエスト ID（request-id。副）です。CloudTrail での追跡には前者を、Anthropic のサポートチケットには後者を使います。
長いリクエストの扱い
公式は10分を超えるような長時間のリクエストではストリーミング Messages API か Message Batches API を使うことを推奨しています。ストリーミングも Batches も使わずに max_tokens を大きく設定するのは避けてください。理由は2つあります。
- ネットワークによっては、一定時間アイドルな接続を切断します。その場合、Anthropic からの応答を受け取らないままリクエストが失敗するかタイムアウトします。
- ネットワークの信頼性はまちまちです。Message Batches API なら、途切れない接続を維持する代わりに結果をポーリングできるので、ネットワーク起因のリスクを管理できます。
直接 API を叩く実装なら、TCP のソケット keep-alive を設定するとアイドル切断の影響を減らせます。公式 SDK はこれを自動で行っており、加えて非ストリーミングの Messages API リクエストが10分のタイムアウトを超えないと見込まれることを検証します。
イベントを逐次処理する必要が無いなら、SDK にストリームを消費させて完成した Message オブジェクトを受け取れます。これは非ストリーミング呼び出しの戻り値と同一です。
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-sonnet-5",
) as stream:
message = stream.get_final_message()この書き方なら、コードの構造を非ストリーミングのまま保ちつつ、接続の切断リスクだけを下げられます。
よくあるバリデーションエラー
公式が個別に挙げているバリデーションエラーがいくつかあります。いずれもモデルの世代差に由来するもので、モデルを乗り換えたときに出ます。
1. プレフィルが未対応（400 invalid_request_error）
Claude 4.6 以降のモデルと Claude Mythos Preview は、アシスタントメッセージのプレフィルに対応していません。プレフィル済みの最後のアシスタントメッセージを送るとエラーになります。代わりに、対応モデルでは Structured Outputs、システムプロンプトでの指示、あるいは output_config.format を使います。
2. thinking ブロックを改変した（400 invalid_request_error）
直近のアシスタントメッセージに含まれる thinking / redacted_thinking ブロックを、編集・並べ替え・除外・再構成してから送り返すとエラーになります。エラーメッセージは問題のあるブロックの位置（例: messages.1.content.0）から始まります。ツール使用時は、アシスタントターンのすべての thinking / redacted_thinking ブロックを受け取ったまま返す必要があります。thinking フィールドが空のブロックも含めてです。コンテンツブロックを type でフィルタしてから再送するアプリケーションでは、両方の型を残してください。
3. 拡張思考が未対応（400 invalid_request_error）
Claude 4.7 以降のモデルからは拡張思考が削除されました。thinking: {"type": "enabled"} を送るとエラーになります。代わりに thinking: {"type": "adaptive"} と output_config.effort を使います。
4. アダプティブ思考が未対応（400 invalid_request_error）
逆に、拡張思考しか対応しないモデル（Claude 4.5 以前）に thinking: {"type": "adaptive"} を送るとエラーになります。これらのモデルでは thinking: {"type": "enabled", "budget_tokens": N} を使います。
5. 思考を無効化できない（400 invalid_request_error）
Claude Fable 5・Claude Mythos 5・Claude Mythos Preview では思考が常時有効です。thinking: {"type": "disabled"} はエラーになります。注意点として、Fable 5 と Mythos 5 では、エラーメッセージ自身が提案する "thinking.type.enabled" も拒否されます。thinking パラメータを省略すればアダプティブ思考で動きます。思考を切らずに応答から思考内容だけを除きたい場合は、thinking の設定に display: "omitted" を指定します。