本番環境におけるAI APIの失敗
AI機能が午前2時に壊れたとき、エラーメッセージだけでは事の真相がわからないことがほとんどです。私は1年間、OpenAIやAnthropicの統合運用を行ってきました。その中で、デバッグの観点から失敗を分類する方法を学びました。
レート制限への対応
OpenAIの429エラーには異なる原因があります。どのように対処すべきかを知るには、エラーコードを確認する必要があります。
- 1分あたりのリクエスト数 (RPM) の制限は、数秒で回復します。
- 1分あたりのトークン数 (TPM) の制限は、60秒で回復します。
- 月間クォータの枯渇は、クレジットを追加するか請求サイクルがリセットされるまで解消されません。
クォータの問題に対して指数バックオフ（exponential backoff）を使用しないでください。時間の無駄になります。
Anthropicの529エラーは、プロバイダーが過負荷であることを意味します。これは503エラーと同様に扱ってください。問題はプロバイダー側にあります。一旦リクエストを控え、チームに通知してください。
400エラーへの対応
これらの失敗は、通常、実装側に原因があります。以下の3つのパターンに注意してください。
- モデルバージョンの不一致。ある場所で名前を更新したが、リトライハンドラー内では更新し忘れている。
- コンテキストウィンドウのオーバーフロー。会話履歴が大きくなりすぎた。これは、不適切な切り詰め（truncation）ロジックによってよく発生します。
- スキーマ検証の失敗。JSON構造にサポートされていない型や再帰的な参照が含まれている。
これらを解決するには、400エラーが発生した際の完全なリクエストペイロードをログに記録してください。その際、まずユーザーデータを伏せ字にしてください。レスポンスボディを見れば、どのフィールドが失敗したのか正確にわかります。
タイムアウトへの対応
タイムアウトは、プロバイダー側には何も問題が見えないため、追跡が困難です。
- 接続タイムアウト（Connect timeout）。ハンドシェイクに失敗しました。これはプロバイダーの瞬断（brownout）やDNSの問題で発生します。送信側のネットワークを確認してください。
- 読み取りタイムアウト（Read timeout）。モデルの生成は開始されましたが、完了しませんでした。アプリ側で、部分的なストリーミング出力を処理できるようにする必要があります。
- ゲートウェイタイムアウト (504)。プロキシが先にタイムアウトしました。リクエストはプロバイダー側でまだ実行されている可能性があります。リトライする前に、重複排除（deduplication）を行ってください。
デバッグの際は、接続タイムアウトと読み取りタイムアウトを分けて考えてください。Time-to-first-token（最初のトークンが届くまでの時間）をログに記録することで、どこにレイテンシが発生しているかを特定できます。
プロバイダーの問題への対応
- 500エラーは、2秒後に1回リトライするだけで解決することがよくあります。
- 503エラーは、サービスが低下していることを意味します。プロバイダーのステータスページにインシデントが表示されている場合は、サーキットブレーカー（circuit breaker）を使用してください。
- 常にどのモデルバージョンが失敗したかを記録してください。モデルによって信頼レベルが異なります。
ログを見てすぐにSlackへ飛びつくのはやめましょう。まずはプロバイダーのステータスページを確認してください。そうすることで、20分間のパニックを回避できます。
Optional learning community: https://t.me/GyaanSetuAi