NNexithDocs
ステータスダッシュボード ↗
概要とクイックスタートモデルカタログガイドAPI リファレンス連携OAuth2 / OIDC

エラーとレート制限

対象:すべての /v1 エンドポイント


1. エラー形式#

すべての非ストリーミングエラーレスポンスボディは以下に統一されています:

{
  "error": {
    "message": "The model 'gpt-4o' does not exist.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
  • message は人間が読むためのもので、安定性は保証されません。ロジック判定には使用しないでください。
  • code は機械可読で、分岐処理に使用します。
  • type は大分類です(authentication_error / rate_limit_error / billing_error / invalid_request_error / server_error)。

2. エラーコード表#

code HTTP 意味 対処の推奨
missing_api_key 401 認証情報がない Authorization: Bearer を追加
invalid_api_key 401 Key が存在しない/失効済み Key を交換
invalid_token 401 JWT が期限切れまたは無効 再ログイン
unauthorized 401 その他の認証失敗 認証情報を確認
forbidden 403 権限なし(例:nx- Key で /v1/images/edits を呼び出し) JWT に変更
invalid_request 400 パラメータが不正 message に従って修正
model_not_found 404 モデルが存在しない/未公開 GET /v1/models で確認
not_found 404 リソースが存在しない、または現在のユーザーに属さない ID を確認
conflict 409 一意性制約の競合 照会してから再試行
payload_too_large 413 リクエストボディ/ファイルが上限超過 ファイルを縮小(ファイル ≤10MB、グローバル body ≤32MB)
rate_limit_exceeded 429 RPM 超過 Retry-After に従ってバックオフ
token_rate_limit_exceeded 429 TPM 超過 Retry-After に従ってバックオフ
quota_exceeded 429 プランの月次クォータを使い切り プランをアップグレードするか翌月まで待つ
insufficient_balance 402 残高不足 チャージ後に再試行
inference_unavailable 502 アップストリームが利用不可(フェイルオーバー試行済み) 再試行可能
model_overloaded 503 アップストリームが過負荷 再試行可能
internal_error 500 サーバー例外 再試行。継続して失敗する場合は障害をご報告ください

アップストリームの実際のモデル名、プロバイダー URL、元のエラーテキストはレスポンスに現れません(不透明性のレッドライン)。 ジョブ関連のエラーは固定文言のみを返します。


3. レート制限#

(API Key, モデル) 単位でバケット分けし、1 分間のウィンドウで判定します。解決順序:

  1. Key レベルの上書き(コンソールで設定)
  2. モデルレベルのデフォルト
  3. プランのデフォルト
  4. システムフォールバック:60 RPM / 40,000 TPM

429 レスポンスヘッダー#

Header 説明
X-RateLimit-Limit-Requests RPM 上限
X-RateLimit-Remaining-Requests この 1 分間の残りリクエスト数(超過時は 0)
X-RateLimit-Reset ウィンドウのリセット時刻(Unix 秒)
X-RateLimit-Limit-Tokens TPM 上限
X-RateLimit-Remaining-Tokens この 1 分間の残り token(超過時は 0)
Retry-After 推奨待機秒数

クライアントへの推奨#

import time, random
from openai import OpenAI, RateLimitError

def call_with_retry(fn, attempts=4):
    for i in range(attempts):
        try:
            return fn()
        except RateLimitError as e:
            wait = float(e.response.headers.get("Retry-After", 1))
            time.sleep(wait + random.uniform(0, 0.5))
    raise
  • 429 / 502 / 503 / 500 のみ再試行してください。4xx のパラメータエラーは再試行しても無意味です。
  • 指数バックオフ + ジッター。Retry-After を尊重してください。
  • 画像ジョブは非同期です。送信の 202 は生成完了を意味しないため、送信を再試行する場合は idempotency_key を再利用してください。

4. 冪等性#

エンドポイント 冪等キー セマンティクス
/v1/images/generations idempotency_key(任意) 同一ユーザー・同一キーは元のジョブを返す
/v1/images/edits idempotency_key(任意) 同上

テキストチャットリクエストには冪等性の保証はありません。ネットワーク再試行は新たな課金リクエストを発生させます。


5. 課金に関する状態#

シナリオ 動作
残高不足 アップストリームに到達する前に 402。費用は発生しません
リクエスト途中の失敗 予約額を全額返金
ジョブの失敗/キャンセル 予約額を全額返金
ストリーミング開始後の切断 配信済み内容に基づいて精算。ゼロ配信は課金しません