← レッスンに戻る
第3章 · Claude API入門

エラー処理とレートリミット

Errors & Rate Limits · 約 10 分

重要キーワード

English日本語説明
Rate Limit レートリミット 単位時間あたりの呼び出し上限 (RPM/TPM)
Exponential Backoff 指数バックオフ 失敗ごとに待機時間を倍々で伸ばすリトライ戦略
Idempotency 冪等性 同じ操作を何度繰り返しても結果が変わらない性質
Retry-After リトライ後待機時間 429 で返るヘッダ。次の試行までの待ち秒数

エラー処理

Anthropic SDK は HTTP ステータスに応じた例外クラスを返します。
例外 ステータス 意味
BadRequestError 400 リクエスト不正
AuthenticationError 401 API キー誤り
PermissionDeniedError 403 権限不足
NotFoundError 404 モデル ID 等が無効
RateLimitError 429 レート上限超え
APIStatusError 5xx サーバー側エラー
APIConnectionError - 通信失敗

リトライ付きの呼び出し

wzxhzdk:1

SDK 標準のリトライ機構

Anthropic(max_retries=3, timeout=60) のように、SDK 自体にもリトライ・タイムアウト設定があります。 シンプルな用途ならまずはこちらで十分。

レートリミット (Rate Limit)

Anthropic はティアごとに RPM (リクエスト/分), TPM (トークン/分) が決まっています。 - 開発初期: 低い上限。 - 使用量・支払いが増えると 自動昇格 または申請で引き上げ可能。

Retry-After ヘッダ

429 のレスポンスには retry-after ヘッダが含まれることがあるので、 これを尊重して待機するのが行儀の良い実装です。SDK は自動で読みます。

Idempotency (冪等性)

同じリクエストを再送しても安全か? Anthropic の messages API は副作用なし なので、リトライしても問題ありません。 ただしユーザー側でログ・課金処理を多重に走らせないよう注意。

よく出るエラーと診断

エラーメッセージ 原因 対処
Invalid API Key キーが間違い・失効 Console で確認
model not found モデル ID 誤り claude-sonnet-4-6 のような正しい ID
max_tokens too large プランの上限超え 引き下げる
prompt is too long コンテキスト超過 入力短縮 / モデル変更
429 レート超過 バックオフ
overloaded_error サーバー過負荷 バックオフして再試行

サーキットブレーカー

連続して失敗するときは 一時停止 (circuit breaker) を入れて、 下流サービスが過負荷で潰れるのを防ぎます。 wzxhzdk:0

観察

エラー応答もモデルに考えさせると面白い学びになります。 ▶ エラー対応プランを Claude に

演習問題

演習 1: リトライ付きラッパーを書く

safe_call(prompt, retries=5) 関数を実装し、次の動作を確認してください。 - RateLimitError → exponential backoff + jitter - 5xx エラー → リトライ - 4xx (RateLimit 以外) → 即座に raise

テスト方法: わざと小さい max_tokens にしてエラーを誘発したり、無効なモデル名で 404 を起こしたりして挙動を確認。

スタータープロンプト:
Python で安全な Claude API ラッパー safe_call(prompt, retries=5) を書いてください。
- RateLimitError なら exponential backoff (2**i + random) で再試行
- 5xx は再試行
- 401/403/400 は即座に raise
- 全リトライ失敗時は RuntimeError を raise
anthropic SDK を import 済みとしてコードのみ示してください。
ヒントを見る

from anthropic import RateLimitError, APIStatusError, AuthenticationError を使い分けます。jitter は random.random() で 0〜1 秒のランダム加算が一般的。

理解度チェック

  1. HTTP 429 を返す Anthropic の例外は?
    1. BadRequestError
    2. RateLimitError
    3. PermissionDeniedError
    4. APIStatusError
  2. リトライ戦略として推奨されるのは?
    1. 即時リトライをループ
    2. exponential backoff + jitter
    3. 5 秒 sleep を 100 回
    4. リトライしない
  3. messages API のリトライは安全?
    1. 副作用なしなので安全
    2. 重複課金が発生するので危険
    3. アカウント停止される
    4. 履歴が壊れる
  4. Circuit Breaker の主目的は?
    1. 電気代節約
    2. 下流サービス過負荷の連鎖を防ぐ
    3. API キー保護
    4. テストの自動化
解答と解説を見る
  1. B — 429 = Rate Limit Exceeded で、RateLimitError がスローされます。
  2. B — 指数バックオフ + ランダム揺らぎが業界標準です。
  3. A — Anthropic 側に副作用はないため、リトライしても基本的に安全です。
  4. B — 失敗連発時に一時停止して下流を守るパターンです。