Background texture
ModelMax

エラー処理

ModelMax は標準的な HTTP ステータスコードと JSON エラーボディを返します。このガイドでは、主なエラーシナリオと処理方法を説明します。

エラーレスポンス形式

すべてのエラーは次の構造に従います。

{
  "error": {
    "message": "human-readable error description",
    "type": "error_type"
  }
}

ステータスコード

クライアントエラー

ステータス種類意味対応
400bad_requestリクエストボディが不正、必須フィールド不足、または非対応モデルリクエストを修正
401unauthorizedAPI キーがない、または無効API キーを確認
402insufficient_balanceアカウント残高が 0 以下アカウントをチャージ

サーバーエラー

ステータス種類意味対応
500internal_error予期しないサーバーエラー少し待って再試行
502bad_gateway上流プロバイダーがエラーを返した再試行、または別モデルを試す

よくあるエラーの処理

残高不足 (402)

これはリクエストがプロバイダーへ到達する前に返されます。課金は発生しません。

{
  "error": {
    "message": "insufficient balance",
    "type": "insufficient_balance"
  }
}

from openai import OpenAI, APIStatusError

client = OpenAI(api_key="your-key", base_url="https://api.modelmax.io/v1")

try:
    response = client.chat.completions.create(
        model="gemini-3-flash-preview",
        messages=[{"role": "user", "content": "Hello"}],
    )
except APIStatusError as e:
    if e.status_code == 402:
        print("Insufficient balance — please top up your account.")
    elif e.status_code == 401:
        print("Invalid API key — check your credentials.")
    else:
        print(f"API error {e.status_code}: {e.message}")

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "your-key", baseURL: "https://api.modelmax.io/v1" });

try {
  const response = await client.chat.completions.create({
    model: "gemini-3-flash-preview",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (error instanceof OpenAI.APIError) {
    if (error.status === 402) {
      console.error("Insufficient balance — please top up.");
    } else if (error.status === 401) {
      console.error("Invalid API key.");
    } else {
      console.error(`API error ${error.status}: ${error.message}`);
    }
  }
}

無効なモデル (400)

{
  "error": {
    "message": "model not found: gpt-4o",
    "type": "bad_request"
  }
}

上流エラー (502)

上流プロバイダー（Bedrock、Gemini など）がエラーを返した状態です。プロバイダー側のレート制限、一時障害、コンテンツポリシー違反などで発生します。

あるモデルで 502 エラーが繰り返し発生する場合は、別プロバイダーの別モデルを試してください。たとえば Bedrock モデルから Gemini モデルへ切り替えます。

動画生成エラー

動画タスクは非同期で失敗することがあります。status と error フィールドを確認してください。

{
  "request_id": "...",
  "status": "FAILED",
  "error": "content policy violation"
}

リトライ戦略

一時的なエラー（500、502）には、単純な指数バックオフが有効です。

import time
from openai import OpenAI, APIStatusError

client = OpenAI(api_key="your-key", base_url="https://api.modelmax.io/v1")

def chat_with_retry(messages, model="gemini-3-flash-preview", max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except APIStatusError as e:
            if e.status_code in (500, 502) and attempt < max_retries - 1:
                wait = 2 ** attempt
                print(f"Retrying in {wait}s...")
                time.sleep(wait)
            else:
                raise