第3章 · Claude API Basics
エラー処理とレートリミット
Errors & Rate Limits
→ で次のスライド · F でフルスクリーン · N で講師ノート · Esc で終了
重要キーワード
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:0
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:1
観察
エラー応答もモデルに考えさせると面白い学びになります。
▶ エラー対応プランを Claude に
あなたは API クライアント設計をレビューする SRE です。Anthropic API の RateLimitError と APIStatusError(5xx) に対するリトライ戦略を、擬似コードで提示してください。考慮点も箇条書きで。Hands-on Exercise
演習: リトライ付きラッパーを書く
safe_call(prompt, retries=5) 関数を実装し、次の動作を確認してください。
- RateLimitError → exponential backoff + jitter
- 5xx エラー → リトライ
- 4xx (RateLimit 以外) → 即座に raise
テスト方法: わざと小さい max_tokens にしてエラーを誘発したり、無効なモデル名で 404 を起こしたりして挙動を確認。
🎉
まとめ
お疲れ様でした!