エラーハンドリングとレート制限
レート制限の例外、認証エラー、タイムアウトなどの一般的なAPIエラーに対し、リトライロジックと指数バックオフのパターンを使って対処します。
「エラーハンドリングとレート制限」はCoddyKit上の無料AI Engineering Academyレッスンです。 これはレッスン4/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはAI Engineering Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 AI Engineering Academyコースには全4レッスンが含まれています。
API エラーが発生する理由
API 呼び出しでは、過負荷、クォータ不足、ネットワーク切断、不正なリクエストなど、さまざまな問題が起こります。呼び出しが失敗しないと考えて実装すると、脆弱なコードになります。まずはエラーの種類を把握しましょう。
OpenAI のエラータイプの概要
SDK は RateLimitError や AuthenticationError など、具体的な例外を発生させます。再試行する価値があるのは、レート制限やネットワーク切断など一時的なエラーだけです。それ以外は自然には解決しません。
Try-Except でエラーを捕捉する
各呼び出しを try-except で囲み、裸の except ではなく具体的な例外を捕捉します。こうすれば、バグを隠すのではなく、失敗の種類に応じて適切に対応できます。方法はコードで確認しましょう。
import openai
client = openai.OpenAI()
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)
except openai.AuthenticationError as e:
print('Bad API key. Check OPENAI_API_KEY environment variable.')
raise # do not retry
except openai.RateLimitError as e:
print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
print('Network error:', e)
except openai.APIStatusError as e:
print('Server error', e.status_code, e.message)レート制限を理解する
OpenAI では、2種類のレート制限が同時に適用されます。1分あたりのリクエスト数（RPM）と、1分あたりのトークン数（TPM）です。非常に大きなプロンプトを1回送るだけで、TPM の上限に達することがあります。どちらも 429 を返します。
指数バックオフ：適切な再試行戦略
レート制限に達しましたか？待機してから、指数バックオフで再試行します。1秒、2秒、4秒と、毎回2倍に増やします。少しジッターを加え、最大再試行回数も設定して、無限ループを防いでください。コードを確認しましょう。
import time
import random
import openai
client = openai.OpenAI()
def call_with_backoff(messages, max_retries=5):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model='gpt-4o-mini',
messages=messages
)
except openai.RateLimitError:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
time.sleep(wait)
except (openai.APIConnectionError, openai.APIStatusError):
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)tenacity ライブラリを使う
再試行処理を自作せず、tenacityライブラリを使いましょう。関数に @retry を付けるだけで、バックオフ、ジッター、再試行条件を処理してくれます。
from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai
client = openai.OpenAI()
@retry(
wait=wait_random_exponential(min=1, max=60),
stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
return client.chat.completions.create(**kwargs)
response = completion_with_backoff(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)タイムアウトを設定する
応答しないリクエストはアプリを永久に停止させる可能性があるため、必ずタイムアウトを設定します。SDK では、クライアント単位または呼び出し単位で秒数を指定できます。想定するレスポンスの長さに合わせて設定してください。
import openai
# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)
# Or override per request
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
timeout=60.0
)
except openai.APITimeoutError:
print('Request timed out. Try a shorter prompt or increase timeout.')認証エラーを処理する
AuthenticationError（401）は、キーが間違っている、期限切れになっている、または無効化されていることを意味します。再試行しても解決しません。ログを記録してアラートを出し、再試行回数を消費する前に即座に失敗させてください。
import os
import openai
api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
raise EnvironmentError(
'OPENAI_API_KEY not set. Export it before running.'
)
client = openai.OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello'}]
)
except openai.AuthenticationError:
# Do NOT retry - the key itself is invalid
raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')クォータとレート制限の違い
どちらも RateLimitError のように見えますが、意味は異なります。レート制限は1分単位の制限で自然にリセットされますが、クォータ制限は支出上限なので、追加のクレジットが必要です。
デバッグのためにエラーをログに記録する
本番環境では、コンテキストを添えてすべてのエラーをログに記録します。種類、モデル、パラメーター、トークン数、時刻、リクエスト ID を記録してください。そのリクエスト ID が、OpenAI サポートにとって必要な情報です。コードを確認しましょう。
import logging
import openai
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
client = openai.OpenAI()
def safe_completion(model, messages):
try:
response = client.chat.completions.create(
model=model, messages=messages
)
return response
except openai.RateLimitError as e:
logger.warning(
'Rate limit hit',
extra={'model': model, 'error': str(e)}
)
raise
except openai.APIStatusError as e:
logger.error(
'API server error',
extra={
'status_code': e.status_code,
'request_id': e.request_id,
'model': model
}
)
raise本番アプリケーションのエラー処理
堅牢な本番戦略は、回復不能なエラーでは即座に失敗させ、一時的なエラーはバックオフ付きで再試行し、適切なフォールバックを提供することです。1つの API エラーでサーバー全体をクラッシュさせないでください。
クイックチェック
このレッスンで学んだ AI Engineering の概念を理解できているか確認しましょう。
レッスンのまとめ
失敗への対処方法を学びました。OpenAI は具体的な例外を発生させ、レート制限にはジッター付きのバックオフが必要です。認証エラーでは即座に失敗させます。次は強力なプロンプトの作成です。
AI チューターと学ぶ Python — 無料
ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。
- コース
- 30
- レッスン
- 120
よくある質問
「エラーハンドリングとレート制限」レッスンは無料ですか？
はい。「エラーハンドリングとレート制限」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、AI Engineering Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 AI Engineering Academyコースには全4レッスンが含まれています。
「エラーハンドリングとレート制限」で何を学びますか？
レート制限の例外、認証エラー、タイムアウトなどの一般的なAPIエラーに対し、リトライロジックと指数バックオフのパターンを使って対処します。 ブラウザで直接実行するハンズオンコードでAI Engineering Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
AI Engineering Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのAI Engineering Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン4/4です。
「エラーハンドリングとレート制限」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このAI Engineering Academyレッスンでコードを書いて実行できますか？
はい。すべてのAI Engineering Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- Python環境のセットアップ
- Chat Completionsエンドポイント
- パラメーターによるモデルの挙動制御
- エラーハンドリングとレート制限