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

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

中級

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

エラーの全体像​

扱うことになる代表的な HTTP ステータス:

ステータス意味対処
400無効なリクエストペイロードを修正する。そのままリトライしない
401API キーが不正/欠落認証情報を確認する
403許可されていないアクセス/権限を確認する
429レート制限バックオフしてリトライする（retry-after を尊重）
500/529サーバーエラー / 過負荷バックオフ付きでリトライする

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))

（多くの SDK は一時的なエラーを自動でリトライします — 自前のリトライを追加する前に、クライアントのデフォルト挙動を把握しておきましょう。）

レート制限​

制限はアカウント/ティアごとに適用されます（毎分のリクエスト数とトークン数）。制限に達すると、タイミングのヒントとともに 429 が返ります。対策としては、retry-after を尊重する、バーストを平準化する、オフライン作業をバッチ処理する、大量処理のステップには安価なモデル（モデルの選び方）を使う、などがあります。

モデル移行​

モデル ID は日付付き/バージョン付きであり、いずれ非推奨になります。次のようにして自分を守りましょう:

次へ​