メインコンテンツまでスキップ

エラー、レート制限 & 信頼性

中級
What you'll learn
  • HTTP エラーマップを読み、リトライすべきステータスと修正すべきステータスを見分ける
  • 一時的なエラーを、上限付きの指数バックオフとジッターでリトライする
  • retry-after、平滑化、バッチ処理、より安価なモデルでレート制限に対処する
  • モデルの廃止と移行から自分のコードを切り離す

本番コードはネットワークサービスと通信するため、失敗を前提にしなければなりません。ここで少し構造を持たせるだけで、不安定な連携と信頼できる連携の差が生まれます。

エラーマップ​

扱うことになる典型的な HTTP ステータス：

ステータス意味対処
400不正なリクエストペイロードを修正；そのままリトライしない
401API キーが不正/欠落認証情報を確認
403許可されていないアクセス権/権限を確認
429レート制限バックオフしてリトライ（retry-after を尊重）
500/529サーバーエラー / 過負荷バックオフ付きでリトライ
Pro tip
  • SDK はこれらを型付きの例外として表面化するので、文字列を解析する代わりにきれいに分岐できます。

バックオフ付きリトライ​

一時的なエラー（429、5xx）には、上限付きの指数バックオフ + ジッターでリトライします：

import time, random
for attempt in range(5):
    try:
        return client.messages.create(...)
    except (RateLimitError, APIStatusError) as e:
        if attempt == 4 or not should_retry(e):
            raise
        time.sleep(min(2 ** attempt + random.random(), 30))
Watch out
  • 多くの SDK は一時的なエラーを自動でリトライします — 自前のリトライを追加する前にクライアントのデフォルトを把握しないと、リトライが二重になることがあります。

レート制限​

制限はアカウント/ティアごと（1分あたりのリクエスト数とトークン数）に適用されます。制限に達すると、タイミングのヒント付きで 429 が返ります。上限を超えないための戦略：

Guided walkthrough1 of 4
  1. 429 を受け取ったら、レスポンスのタイミングのヒントを読み、その時間だけ待ってからリトライします。

大量のステップに適したモデルの選び方については モデルの選び方 を参照してください。

モデル移行​

モデル ID は日付/バージョン付きで、廃止されます。自分を切り離しておきましょう：

Key takeaways
  • 400/401/403 はあなたの問題——リクエストか認証情報を修正し、やみくもにリトライしない。429 と 500/529 はリトライ可能。
  • 一時的なエラーは、上限付きの指数バックオフ + ジッターでリトライする（例：min(2 ** attempt + random(), 30)）。
  • 429 では：retry-after を尊重し、バーストを平滑化し、オフライン作業をバッチ化し、大量のステップをより安価なモデルに振り分ける。
  • モデル ID は設定から読み、廃止を監視し、モデル移行時には評価を再実行する。

理解度チェック

0/4
  1. 400 不正なリクエストを受け取りました。どうすべきですか？
  2. バックオフ付きでリトライすべきステータスはどれですか？
  3. 指数バックオフにジッターを加えるのはなぜですか？
  4. 推奨されるレート制限戦略では「ない」ものはどれですか？

次へ​