エラーハンドリング

このガイドでは、诺玛AI のエラーレスポンスフォーマット、よくあるエラー、そしておすすめのしょりほうほうをせつめいします。

エラーレスポンスフォーマット#

すべてのエラーレスポンスは、とういつされた JSON フォーマットにしたがいます。

コード
{
  "error": {
    "code": "invalid_api_key",
    "message": "提供された API Key が無効です。確認のうえ再試行してください。",
    "type": "authentication_error"
  }
}

HTTP ステータスコード#

ステータスコード

タイプ

せつめい

リトライすべきか

`400`

`invalid_request_error`

リクエストパラメータエラー

❌ パラメータをしゅうせいしてリトライ

`401`

`authentication_error`

API Key がむこう、またはけつらく

❌ API Key をかくにん

`403`

`permission_error`

けんげんがふそくしています

❌ アカウントけんげんをかくにん

`404`

`not_found_error`

モデルまたはリソースがありません

❌ モデル ID をかくにん

`429`

`rate_limit_error`

レートリミットにたっしました

✅ まってからリトライ

`500`

`internal_error`

サーバーないぶエラー

✅ あとでリトライ

`502`

`upstream_error`

アップストリームモデルプロバイダーのエラー

✅ モデルをかえる、またはリトライ

`503`

`service_unavailable`

サービスがいちじてきにつかえません

✅ あとでリトライ

よくあるエラーとたいおう#

401 — API Key がむこう

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

たいおう:

  • API Key が `sk-` プレフィックスをふくめてただしくコピーされているかかくにんする
  • Key がきげんぎれ、またはむこうかされていないかかくにんする
  • かんきょうへんすうがただしくロードされているかかくにんする

429 — レートリミット

たいおう:

  • レスポンス Header の `x-ratelimit-reset-requests` をかくにんする
  • exponential backoff でリトライをじっそうする
  • よりたかいクォータがひつようなら、サポートにちょうせいをたのむ

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

たいおう:

  • フォールバックでべつのモデルへじどうきりかえする
  • あとでリトライする
  • モデルプロバイダーのステータスページをかくにんする

リトライせんりゃく#

**Exponential Backoff** せんりゃくをつかうことをおすすめします。

コード
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<あなたの APINOMA_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}s 待機後に再試行します...")
            time.sleep(wait)

        except APIConnectionError:
            # ネットワークエラー: 短時間待機後に再試行
            wait = 2 ** attempt
            print(f"接続エラー。{wait}s 待機後に再試行します...")
            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://as.apinoma.com/v1",
    api_key="<あなたの APINOMA_API_KEY>",
    timeout=60.0,  # 60 秒のタイムアウト
    max_retries=3  # SDK 組み込みの再試行
)

ストリーミングリクエストでは、モデルがすべてのコンテンツをつくるのにじかんがかかることがあるため、ながめのタイムアウト(120〜300 びょう)をおすすめします。

ベストプラクティス#

  • リトライできるエラーとできないエラーをわける — 4xx はふつうリクエストしゅうせいがひつようで、5xx はリトライできます
  • exponential backoff をつかう — レートリミットじのひんぱんなリトライをさける
  • さいだいリトライかいすうをせっていする — むげんリトライをふせぐ
  • エラーログをのこす — トラブルシュートをしやすくする
  • フォールバックをせっていする — 诺玛AI の `provider.fallback` でモデルをじどうきりかえする
  • エラーりつをみる — コンソールでエラートレンドをかくにんする

さいしゅうこうしん: 2026 ねん 6 がつ 23 にち