トラブルシューティング

AIエージェントAPIエラーの解決方法：ステータスコード別対処法

Media Lab

AIエージェントAPIエラーの解決方法：ステータスコード別対処法

AIエージェント開発ではAPIエラーは日常茶飯事です。エラーの種類によって原因と対処法が異なり、適切なリトライ戦略の実装も必要です。本記事では、ステータスコード別のエラー対処法と、堅牢なエラーハンドリングの実装方法を解説します。

HTTPステータスコード別エラーと対処法

400 Bad Request（不正なリクエスト）

原因：リクエストの形式が正しくない、必須パラメータの欠如

対処法：

  • リクエストのJSONフォーマットを確認
  • 必須フィールド（model, messages等）が揃っているか確認
  • 入力テキストに許可されていない文字や形式がないか確認
  • APIドキュメントでパラメータの正しい型を確認

401 Unauthorized（認証エラー）

原因：APIキーが無効、期限切れ、または設定ミス

対処法：

  • APIキーをコンソールで確認（新しいキーを発行してテスト）
  • 環境変数の設定が正しいか再確認
  • ベアラートークンの形式が正しいか確認（Authorization: Bearer sk-xxx）

AIエージェントAPIキー設定方法でAPIキーの安全な管理方法を解説しています。

403 Forbidden（アクセス拒否）

原因：アカウントの権限不足、地域制限、プランの制限

対処法：

  • アカウントのプランで対象のモデル/機能が利用可能か確認
  • 組織IDが必要な場合は正しく設定されているか確認
  • 対象地域でサービスが利用可能か確認

429 Too Many Requests（レートリミット）

最も頻繁に遭遇するエラーです。プロバイダーが設定したリクエスト数の上限を超えた際に発生します。

対処法：

  • リクエストの送信間隔を空ける（後述のExponential Backoff）
  • 使用量の多い時間帯を分散させる
  • 上位プランへのアップグレードを検討
  • Retry-Afterヘッダーで指定された時間待機

500 Internal Server Error（サーバーエラー）

原因：APIプロバイダー側のサーバー問題

対処法：

  • プロバイダーのステータスページで障害情報を確認
  • 短時間後にリトライ
  • 問題が継続する場合はサポートに連絡

503 Service Unavailable（サービス停止）

原因：メンテナンス、過負荷状態

対処法：

  • プロバイダーのステータスページを確認
  • 一定時間後（5〜10分）にリトライ

Exponential Backoffの実装

レートリミット（429）やサーバーエラー（5xx）には、待機時間を指数関数的に増やしながらリトライする「Exponential Backoff」が標準的な対処法です。

import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI()

def call_with_retry(messages, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o-mini",
                messages=messages
            )
            return response
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            # Exponential Backoff: 2^attempt秒 + ランダムジッター
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"レートリミット。{wait_time:.1f}秒待機後にリトライ...")
            time.sleep(wait_time)
        except APIStatusError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
            raise

n8nでのエラーハンドリング設定

n8nでワークフローを構築している場合は、各ノードにリトライ設定があります。

ノードの設定画面でRetryオプションを有効にし、最大リトライ回数（例：3回）と待機時間（例：指数関数的増加）を設定します。Error Outputを有効にすることで、失敗時に別のフローを実行することもできます。

AIエージェントのエラートラブルシューティングで解説したログ設定と組み合わせて、エラーの発生状況を追跡します。

エラーアラートの設定

本番環境では、エラーが発生した際に即座に通知を受けられる体制を整えることが重要です。

import requests

def send_slack_alert(error_type, error_message, task_info):
    webhook_url = "https://hooks.slack.com/..."  # Slack Webhook URL
    payload = {
        "text": f"AIエージェントエラー発生\n種類: {error_type}\nメッセージ: {error_message}\nタスク: {task_info}"
    }
    requests.post(webhook_url, json=payload)

まとめ

APIエラーに対する防御的なコーディングは、AIエージェントの本番運用において必須のスキルです。ステータスコードに応じた適切な対処法と、Exponential Backoffによるリトライ戦略を実装することで、エージェントの信頼性を大幅に向上させられます。AIエージェントデバッグのコツと合わせて、堅牢なエラーハンドリング体制を構築しましょう。