Claude APIの500 api_error対処法：再試行後も失敗する場合の扱い

Claude APIからHTTP 500とerror.type: api_errorが返ったら、リクエスト情報を保存し、安全に繰り返せる処理だけを、上限を決めて再試行します。 Anthropicの公式説明では、500はシステム内部で発生した予期しないエラーです。指数バックオフによる再試行が推奨され、続く場合はリクエストIDを添えてサポートへ問い合わせます。APIエラーの公式説明

まずSDKが自動で再試行しているか確認してください。公式Python SDKは対象の一時的な失敗を既定で2回再試行します。アプリがさらに同じ呼び出しを繰り返すと、送信回数と待機時間が増えます。再試行を担当する箇所を一つに決め、終了後も500なら、利用者へ失敗を返すか、期限に余裕のあるジョブを後に回します。Python SDKの再試行設定

500だけを理由に、APIキーの交換、再ログイン、プロンプトの全面的な変更へ進む必要はありません。何を受信したかを残したうえで、Claude StatusのAPI関連情報を確認します。正常表示でも、個別のモデルや接続先が成功するとは限りません。

返された500と、応答が届かないエラーを区別する

HTTPステータス、エラーJSON、実際の接続先を確認します。次はAnthropic APIへ直接接続したときの500の形式を示す例です。リクエストIDは説明用で、実際の呼び出しを示していません。

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Internal server error"
  },
  "request_id": "req_example"
}

error.messageは表示用の文言なので、完全一致による判定よりHTTPステータスと型を使います。公式SDKでは、エラーJSONの代わりに型付き例外が発生します。PythonではAPIStatusErrorのstatus_codeとresponseから返されたHTTP応答を確認できます。エラー形式と型付き例外、Python SDKのエラー処理

この分類は公式APIエラー一覧に基づきます。429のうち利用階層の月間支出上限によるものは、retry-afterがなく、アクセスが再開するまで失敗し続けます。「500以上だから待つ」「エラーだからすべて再送する」と一括処理しないことが大切です。

api_errorという文字列だけ、あるいはno response from API、error sending prompt: internal errorという画面表示だけでは、実際にHTTP 500が返ったか分かりません。リクエストIDが見えなくても、SDKの公開方法や中継サービスのヘッダー処理によっては、HTTP応答自体は得られています。IDの有無ではなく、応答や例外を確認してください。

Claude Codeのターミナルで止まっている場合は、500・529後に元のセッションと実行結果を確認する手順が適切です。Webや連携アプリの表示しか分からない場合は、利用画面と接続先から内部サーバーエラーを切り分ける方法を使えます。本記事では、APIを呼ぶアプリが返された500を扱う方法を進めます。

Python SDKで再試行を任せ、最後の失敗を受け取る

単純な非ストリーミングの文章生成なら、SDKに再試行を任せ、アプリは成功と最終的な失敗を受け取る形にできます。以下は、500の失敗情報をJSONで出力し、終了コード2で処理を終える例です。ジョブ実行側はこの結果を使い、後で再実行するか、失敗として通知するかを決められます。

公式anthropicパッケージを利用し、APIキーを通常の方法で設定済みの環境を前提とします。ANTHROPIC_MODELには、その環境で利用できる実際のモデルIDを設定してください。コードをhandle_500.pyとして保存し、python handle_500.pyで実行します。この例にツールの外部操作やストリームの再開機能はありません。

import json
import os
import sys
from datetime import datetime, timezone

import anthropic


def status_record(exc: anthropic.APIStatusError) -> dict:
    body = exc.body if isinstance(exc.body, dict) else {}
    error = body.get("error")
    error = error if isinstance(error, dict) else {}
    request_id = (
        exc.response.headers.get("request-id")
        or body.get("request_id")
    )
    return {
        "http_status": exc.status_code,
        "error_type": error.get("type"),
        "request_id": request_id,
    }


def main() -> int:
    model = os.environ.get("ANTHROPIC_MODEL")
    if not model:
        raise SystemExit("ANTHROPIC_MODELに利用可能なモデルIDを設定してください")

    context = {
        "model": model,
        "endpoint": "/v1/messages",
        "sdk_max_retries": 2,
        "streaming": False,
    }
    with anthropic.Anthropic(max_retries=2, timeout=20.0) as client:
        try:
            message = client.messages.create(
                model=model,
                max_tokens=128,
                messages=[{"role": "user", "content": "短い挨拶を一文でお願いします。"}],
            )
        except anthropic.APITimeoutError:
            record = {"state": "client_timeout", **context}
            exit_code = 3
        except anthropic.APIConnectionError:
            record = {"state": "connection_error", **context}
            exit_code = 3
        except anthropic.APIStatusError as exc:
            state = "api_500" if exc.status_code == 500 else "other_http_error"
            record = {"state": state, **context, **status_record(exc)}
            exit_code = 2 if exc.status_code == 500 else 4
        else:
            for block in message.content:
                if block.type == "text":
                    print(block.text)
            return 0

    record["recorded_at_utc"] = datetime.now(timezone.utc).isoformat()
    print(json.dumps(record, ensure_ascii=False), file=sys.stderr)
    return exit_code


if __name__ == "__main__":
    sys.exit(main())

max_retries=2は、最初の送信に加えて最大2回の再試行です。成功や再試行を拒否する条件によって、早く終了することもあります。SDKは接続エラー、408、409、429、500以上を既定の対象としており、この例も500だけを再試行する設定ではありません。アプリ側はSDKの呼び出しが終了した後の正確なHTTPステータスで500を区別します。SDKの仕様

InternalServerErrorというクラス名だけで「500」と決めないのも理由があります。公式SDKの文書には500以上のエラーとして記載され、2026年10月4日に確認したPython SDKのmainブランチでは529が別のOverloadedErrorへ分岐します。mainの実装はインストール済みバージョンを保証しないため、コードはAPIStatusError.status_code == 500を使っています。接続例外を含む基底のAPIErrorすべてにstatus_codeがあるとは想定しません。公式SDKのステータス別処理、例外の定義

このコードは、模擬クライアントによるオフライン確認で、成功、500、他のHTTPエラー、接続失敗、タイムアウトの分岐を確認しています。実APIでの復旧率や、待機時間は測定していません。

timeoutを設定しても、全体が20秒で終わるとは限りません

上のtimeout=20.0はクライアントのタイムアウト設定です。再試行とその前の待機を含め、プログラム全体を20秒以内に終える保証ではありません。タイムアウト自体もSDKの再試行対象です。Python SDKのタイムアウト

また、現在の公式説明ではretry-afterがあればその待機指示に従います。確認したPython SDKのmain実装は、retry-after-ms、秒数、HTTP日時を解釈し、正の待機時間を使います。利用中の版での動作を確認し、長い待機指示が利用者の待てる時間を超えるなら、追加の即時送信をせず、後で処理する設計にしてください。公式APIの再試行説明、待機時間の実装

対話画面の待機期限を厳密に守る必要があるなら、API呼び出しを別のジョブに分け、画面の待機終了とジョブの結果を個別に管理します。画面が待つのをやめても、サーバー側の処理が取り消されたとは限らないため、後から得られた結果を同じ業務ジョブに対応付けます。

再試行前に、重複して困る処理がないか確かめる

上の例は短いテキスト生成だけを行います。一方、実際のアプリが生成結果を使ってメールを送る、データを更新する、注文を確定するなら、APIの失敗と業務処理の失敗を分けて扱います。回答が得られなかったことだけでは、すでに実行した外部操作が取り消されたとは分かりません。

業務ジョブにはアプリ側の識別子を付け、送信済み・完了済み・結果不明の操作を保存します。再送する前に実際の記録を照合し、完了した操作を繰り返さないようにします。これはアプリ側の重複防止の設計です。任意のIdempotency-Keyヘッダーを付ければAnthropic Messages APIが必ず重複を防ぐ、という意味ではありません。

SDKの再試行が終わったあと、同じ関数をキューが即時再実行する構成にも注意してください。たとえば、アプリ側で最大3回呼び出し、各呼び出しがSDKで最大2回再試行するなら、送信は最大9回になります。これは「3回の初回送信＋各2回の再試行」の計算例で、実際の全経路の回数を示すものではありません。中継サービスの再試行はさらに別に確認する必要があります。

処理ごとに、再試行を誰が担当するか、いつ失敗を返すか、延期できる期限はいつかを決めます。SDKに任せる構成では、外側のループを増やす前に、SDKが待っている時間と最終結果を確認してください。

HTTP 200の後で応答が途切れた場合

ストリーミングでは、HTTP 200を受信した後にエラーが起こることがあります。この場合、上の非ストリーミング用コードだけでは、応答が最後まで完了したかを判断できません。公式のストリーミングエラー説明

connection lost mid-responseやThe response above may be incompleteに相当する失敗が出たら、受信した内容を未完成として保存し、ストリームの終了状態と実行済みの処理を確認します。再生成したテキストを途中の回答へそのまま追記したり、残ったツール呼び出しを無条件に再実行したりしないでください。どこから再開できるかはアプリの保存方法とSDKの実装に依存します。

500が続いたら、停止・延期・再開の結果を明確にする

同じモデルと接続先で、安全な再試行を終えても500なら、追加送信を止めます。まず利用者やジョブ実行側に「成功していない」という結果を返し、処理の重要度に応じて次の動きを選びます。

公開障害情報がある場合は、その対象と更新内容を確認し、非緊急の仕事を待たせます。障害情報がなくても、回数を増やせば直るとは限りません。送信を一時停止する条件は、アプリの応答期限や失敗の広がりに合わせて決め、すべての連携に共通する「3回失敗したら別サービスへ移る」といった固定ルールにはしません。

復旧の確認は、元の接続先で応答が正常に完了したかを基準にします。ステータスページの色が変わっただけでは、自分の呼び出しの成功を確認できていません。モデルや接続先を一時的に変えて仕事を進めた場合も、「別の条件で成功した」という結果として残します。元の500の原因が判明したことにはなりません。

問い合わせに使えるリクエスト情報を残す

直接Anthropic APIでは、応答ヘッダーのrequest-idとエラーJSONのrequest_idが同じリクエストを識別します。取得できる方を保存してください。成功時のPython SDKレスポンスにある_request_idと、失敗時の例外に付く情報は取得する箇所が異なります。上のコードは失敗したHTTP応答のヘッダーを優先し、なければJSONを確認します。リクエストIDの公式説明

問い合わせでは、取得できた情報を次のようにまとめると、同じ呼び出しを追いやすくなります。

• 発生日時とタイムゾーン、HTTPステータス、error.type、機密情報を除いたエラーメッセージ。
• 各失敗で取得できたリクエストID。見つからない場合は、その旨と、取得できたHTTP情報。
• 実際の接続先、エンドポイント、モデルID、SDKの名前とバージョン、ストリーミングの有無。
• 初回送信と再試行の時刻・結果。SDK、アプリ、キュー、中継サービスそれぞれの再試行設定。
• 入力サイズ、メッセージ数、ツールの有無など、失敗したリクエストの特徴。
• 同じ条件で再発するか、変更した条件があるか、利用者や業務への影響。

上のコードが記録するリクエストIDは、SDKから最後に渡された失敗のものです。内部の再試行すべてのIDを取得するコードではありません。必要なら、利用中のSDKのログ機能や運用基盤で、安全に取得できる範囲の履歴を残します。分からない送信回数やIDを補って書く必要はありません。

原因を絞るときは、まず実際に失敗したモデル、接続先、リクエストの形式を残します。その後、機密情報を除いた最小限の有効な入力でも再発するかを確認できます。簡略化した入力が成功した場合は、元の入力と条件が違うため、元の障害が解消したとは判断しません。プロンプトを小さくすること自体を、500に対する保証された修復方法として扱わないでください。

APIキー、認証ヘッダー、顧客の本文、環境変数の一括出力は問い合わせ用の記録に含めません。エラーメッセージにも入力の一部が含まれていないか確認します。コード例はそのため、メッセージ全文ではなくステータス、型、IDを自動記録します。

中継サービスを使っているなら、まずその運営者へ問い合わせます。アプリが受け取った500と上流の応答を対応付け、上流のHTTPステータスやリクエストIDを確認してもらいます。直接Anthropic APIの500が続く場合は、公式API文書の案内に従い、リクエストIDを添えてサポートへ連絡してください。

よくある質問

500 api_errorが出たら、APIキーを交換すべきですか？

500だけを理由に交換する必要はありません。Anthropic APIの500は内部エラーで、APIキーの問題は401 authentication_errorとして別に説明されています。500の応答を保存し、有限回の再試行後も続くなら問い合わせへ進みます。公式のエラー分類

リクエストIDがない場合は、APIに接続できていませんか？

IDが見えないことだけでは断定できません。中継サービスがヘッダーを省略したり、SDKが別の箇所で公開したりする場合があります。HTTP応答が得られたかを確認し、得られていない接続例外と区別します。実際に取得できたステータス、本文、接続先を残してください。

Claude Statusが正常なら、再試行を続けてよいですか？

正常表示だけでは継続の根拠になりません。個別のリクエストが成功するとは限らないため、アプリで決めた回数と待機の上限で止めます。失敗が続くなら、入力やジョブの状態を保存し、延期や問い合わせを選びます。

Python SDKの再試行は、Claude Codeと同じ回数ですか？

別の仕組みです。公式Python SDKは対象の失敗を既定で2回再試行し、max_retriesで調整できます。Claude Codeの動作はCLIの版や部分応答の状態にも依存するため、Claude Codeでの再開手順を参照してください。Python SDKの仕様