ドキュメントガイドエラー処理とリトライ

エラー処理とリトライ

ステータスコードで分岐し、指数バックオフでリトライして、レート制限や上流の揺らぎに耐える統合を作ります。

原則は 2 つ：HTTP ステータスとエラーの type/status フィールドで分岐する（メッセージはローカライズされるため、テキスト照合は必ず壊れます）。そしてリトライすべきものだけリトライする——パラメータエラーは何度送っても直りません。

ステータスコード別の対処

HTTP	典型的な原因	対処
400	ボディ不正・フィールド欠落	リクエストを修正。リトライ不可。
401 / 403	キー無効/停止、IP 拒否	キーと設定を確認。リトライ不可。
402	残高またはキー上限切れ	チャージまたは上限変更。自動リトライ不可（結果は変わりません）。
404	モデル不明/未対応エンドポイント	モデル一覧で id を確認。
413	ペイロード過大	インラインメディアを圧縮するかエンドポイント変更。リトライ不可。
429	RPM/同時実行制限	指数バックオフ + ジッターでリトライ。
502 / 503	上流障害/ゲートウェイ過負荷	バックオフしてリトライ。ゲートウェイ自体も先にフェイルオーバーを試みます。

指数バックオフの例

retry.py

import random
import time

from openai import OpenAI, APIStatusError

client = OpenAI(api_key="sk-sole-...", base_url="https://api.soleapi.com/v1")

RETRYABLE = {429, 502, 503}

def create_with_retry(**kwargs):
    delay = 1.0
    for attempt in range(5):
        try:
            return client.responses.create(**kwargs)
        except APIStatusError as e:
            if e.status_code not in RETRYABLE or attempt == 4:
                raise
            time.sleep(delay + random.random())  # jitter
            delay = min(delay * 2, 30)

OpenAI と Anthropic の公式 SDK は 429/5xx を自動リトライします（max_retries）。多くの場合はそれで十分です。自前で書く場合は必ずジッターを入れ、多数のクライアントが同時にリトライする雪崩を防いでください。

トラブルシューティング

エラーレスポンス全体と発生時刻を記録してください。type/status フィールドと HTTP ステータスでカテゴリを特定できます。エラーコード参照。
散発的な 5xx は正常な揺らぎです。継続する場合のみ調査してください。コンソールの利用明細で失敗リクエストを個別に照合できます。
429 が頻発する場合はまず並列数を下げ、それでも足りなければ管理者に上限調整を相談してください。レート制限とクォータ参照。