エラーとレート制限
対象:すべての
/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 分間のウィンドウで判定します。解決順序:
- Key レベルの上書き(コンソールで設定)
- モデルレベルのデフォルト
- プランのデフォルト
- システムフォールバック: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。費用は発生しません |
| リクエスト途中の失敗 | 予約額を全額返金 |
| ジョブの失敗/キャンセル | 予約額を全額返金 |
| ストリーミング開始後の切断 | 配信済み内容に基づいて精算。ゼロ配信は課金しません |