错误处理

ModelMax 返回标准 HTTP 状态码和 JSON 错误体。本指南涵盖所有错误场景及其处理方式。

错误响应格式

所有错误遵循以下结构：

{
  "error": {
    "message": "人类可读的错误描述",
    "type": "error_type"
  }
}

状态码

客户端错误

状态码	类型	含义	操作
`400`	`bad_request`	请求体无效、缺少字段或不支持的模型	修复请求
`401`	`unauthorized`	缺少或无效的 API 密钥	检查 API 密钥
`402`	`insufficient_balance`	账户余额为零或负数	充值账户

服务端错误

状态码	类型	含义	操作
`500`	`internal_error`	意外的服务器错误	稍后重试
`502`	`bad_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("余额不足 — 请充值账户。")
    elif e.status_code == 401:
        print("无效的 API 密钥 — 请检查凭据。")
    else:
        print(f"API 错误 {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("余额不足 — 请充值。");
    } else if (error.status === 401) {
      console.error("无效的 API 密钥。");
    } else {
      console.error(`API 错误 ${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"将在 {wait} 秒后重试...")
                time.sleep(wait)
            else:
                raise