Skip to Content
開発ドキュメントガイドエラーハンドリング

エラーハンドリング

このガイドでは、OfoxAI APIのエラーレスポンス形式、よくあるエラーシナリオ、推奨される対処戦略を紹介します。

エラーレスポンス形式

すべてのエラーレスポンスは統一された JSON 形式に従います：

{
  "error": {
    "code": "invalid_api_key",
    "message": "提供された API Key が無効です。確認してからリトライしてください。",
    "type": "authentication_error"
  }
}

HTTPステータスコード

ステータスコードタイプ説明リトライすべきか
400invalid_request_errorリクエストパラメータエラー❌ パラメータを修正してリトライ
401authentication_errorAPI Key が無効または欠落❌ API Key を確認
403permission_error権限不足❌ アカウント権限を確認
404not_found_errorモデルまたはリソースが存在しない❌ モデル ID を確認
429rate_limit_errorレート制限にトリガー✅ 待機後にリトライ
500internal_errorサーバー内部エラー✅ しばらく後にリトライ
502upstream_errorアップストリームモデルプロバイダーエラー✅ モデルを変更またはリトライ
503service_unavailableサービスが一時的に利用不可✅ しばらく後にリトライ

よくあるエラーと解決策

401 — API Key が無効

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

解決策：

  • API Key が正しくコピーされているか確認（sk- プレフィックスを含む）
  • Key が期限切れまたは無効化されていないか確認
  • 環境変数が正しくロードされているか確認

429 — レート制限

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

解決策：

  • レスポンスヘッダーの x-ratelimit-reset-requests を確認
  • エクスポネンシャルバックオフリトライを実装
  • より高いクォータが必要な場合は、サポートにお問い合わせの上、調整を申請

502 — アップストリームエラー

{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

解決策：

  • フォールバックを使用して代替モデルに自動切り替え
  • しばらく後にリトライ
  • モデルプロバイダーのステータスページを確認

リトライ戦略

**エクスポネンシャルバックオフ（Exponential Backoff）**戦略の使用を推奨します：

retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<あなたの OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """エクスポネンシャルバックオフ付きリトライラッパー"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: 待機後にリトライ
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"レート制限に到達しました。{wait:.1f}秒後にリトライします...")
            time.sleep(wait)
 
        except APIConnectionError:
            # ネットワークエラー：短時間待機後にリトライ
            wait = 2 ** attempt
            print(f"接続エラー。{wait}秒後にリトライします...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: サーバーエラー、リトライ
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: クライアントエラー、リトライしない
                raise
 
    raise Exception(f"{max_retries} 回リトライしましたが失敗しました")
 
# 使用例
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "こんにちは"}]
)

タイムアウト設定

API 呼び出しに適切なタイムアウト時間を設定することを推奨します：

# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<あなたの OFOXAI_API_KEY>",
    timeout=60.0,  # 60秒タイムアウト
    max_retries=3  # SDK 内蔵リトライ
)
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<あなたの OFOXAI_API_KEY>',
  timeout: 60000,  // 60秒タイムアウト
  maxRetries: 3    // SDK 内蔵リトライ
})

ストリーミングリクエストにはより長いタイムアウト時間（120〜300秒）の設定を推奨します。モデルが完全なコンテンツを生成するまでに時間がかかる場合があるためです。

ベストプラクティス

  1. リトライ可能なエラーとリトライ不可なエラーを区別する — 4xx は通常リクエストの修正が必要、5xx はリトライ可能
  2. エクスポネンシャルバックオフを使用する — レート制限時の頻繁なリトライを回避
  3. 最大リトライ回数を設定する — 無限リトライを防止
  4. エラーログを記録する — 問題の調査に役立てる
  5. フォールバックを設定する — OfoxAI の provider.fallback パラメータでモデルを自動切り替え
  6. エラー率をモニタリングする — コンソールでエラーの傾向に注目
Last updated on
構造化出力プロバイダールーティング