错误处理

通过 OpenModel 发起 API 请求时，你可能会遇到两类错误：由 OpenModel 网关返回的网关错误，以及由上游 AI 提供商返回并透传的上游错误。

错误分类

网关错误

网关错误来源于 OpenModel 本身，在请求尚未到达上游提供商时发生（如认证失败、限流、余额不足）。

对于代理端点（/v1/responses、/v1/messages、/v1beta/models/*），网关错误会以与你使用的 API 协议匹配的对应格式返回，确保 SDK 的错误处理机制能正常工作：

OpenAI 格式（/v1/responses）：

{
  "error": {
    "message": "API key is invalid or has been revoked",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Anthropic 格式（/v1/messages）：

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "API key is invalid or has been revoked"
  }
}

Gemini 格式（/v1beta/models/*）：

{
  "error": {
    "code": 401,
    "message": "API key is invalid or has been revoked",
    "status": "UNAUTHENTICATED"
  }
}

对于管理 API 端点（/web/v1/*），错误使用标准响应格式：

{
  "success": false,
  "data": null,
  "error": {
    "code": "UNAUTHORIZED",
    "msg": "API key is invalid or has been revoked"
  }
}

Messages 协议供应商： 所有使用 Messages 协议的供应商（Anthropic、DeepSeek、Xiaomi、Kimi、MiniMax、Zai）返回上述 Anthropic 格式的错误。DashScope 通过 /v1/responses 访问时返回 OpenAI 格式的错误，通过 /v1/messages 访问时返回 Anthropic 格式的错误。你现有的 SDK 错误处理代码无需修改即可适用于同一协议下的所有供应商。

上游错误

当上游 AI 提供商返回错误时，OpenModel 会以提供商的原始格式透传。这意味着错误结构取决于你使用的 API 格式：

OpenAI 格式：

{
  "error": {
    "message": "The model `gpt-5` does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Anthropic 格式：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be less than 8192"
  }
}

Gemini 格式：

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'contents'",
    "status": "INVALID_ARGUMENT"
  }
}

HTTP 状态码

状态码	含义	处理方式
`400`	请求格式错误或参数无效	修正请求后重试
`401`	未授权 — API Key 无效或缺失	检查 API Key
`402`	余额不足 — 需要充值	在控制台充值
`403`	禁止访问 — 权限不足	确认账户权限
`404`	未找到 — 无效的端点或模型	检查 URL 和模型名称
`429`	请求过多 — 触发频率限制	使用指数退避重试
`500`	内部服务器错误 — 网关异常	使用退避策略重试
`502`	网关错误 — 上游提供商不可达	使用退避策略重试
`503`	服务不可用 — 临时过载	使用退避策略重试
`504`	网关超时 — 上游提供商响应超时	使用退避策略重试

重试策略

并非所有错误都应该重试。以下是推荐的处理方式：

可重试的错误

对以下状态码使用指数退避加随机抖动进行重试：

429 — 频率限制。等待后重试。
500 — 内部服务器错误。通常是暂时性的。
502 — 网关错误。上游提供商可能暂时不可用。
503 — 服务不可用。临时过载。
504 — 网关超时。上游提供商响应超时。

不可重试的错误

不要重试以下错误 — 请求本身存在问题：

400 — 修正请求体或参数。
401 — 检查 API Key。
403 — 确认权限设置。
404 — 检查端点 URL 或模型名称。

指数退避与随机抖动

良好的重试策略应使用指数退避配合随机抖动，以避免"惊群效应"：

import time
import random
from openai import OpenAI, APIStatusError

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

def make_request_with_retry(max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.responses.create(
                model="gpt-5.4",
                input="你好！",
            )
        except APIStatusError as e:
            if e.status_code in (429, 500, 502, 503, 504):
                if attempt == max_retries - 1:
                    raise
                # 指数退避：1s, 2s, 4s, 8s, 16s + 随机抖动
                delay = (2 ** attempt) + random.random()
                print(f"将在 {delay:.1f}s 后重试（第 {attempt + 1} 次）")
                time.sleep(delay)
            else:
                raise  # 不重试客户端错误

超时处理

非流式请求

为标准请求设置合理的超时时间。大多数补全请求在 30-60 秒内完成，但复杂提示词或大量输出可能需要更长时间：

import httpx
from openai import OpenAI

client = OpenAI(
    base_url="https://api.openmodel.ai/v1",
    api_key="your-api-key",
    timeout=httpx.Timeout(60.0, connect=10.0),
)

流式请求

流式请求的超时时间应设置得更长，因为连接在整个生成过程中保持打开：

import httpx
from openai import OpenAI

client = OpenAI(
    base_url="https://api.openmodel.ai/v1",
    api_key="your-api-key",
    timeout=httpx.Timeout(300.0, connect=10.0),
)

错误处理模式

Python — 全面的错误处理

from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

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

try:
    response = client.responses.create(
        model="gpt-5.4",
        input="你好！",
    )
    print(response.output_text)

except APIConnectionError:
    print("无法连接到 API，请检查网络。")

except APITimeoutError:
    print("请求超时，请重试或增加超时时间。")

except APIStatusError as e:
    if e.status_code == 401:
        print("API Key 无效，请检查凭证。")
    elif e.status_code == 429:
        print("触发频率限制，请降低请求速率。")
    elif e.status_code >= 500:
        print(f"服务器错误（{e.status_code}），请稍后重试。")
    else:
        print(f"API 错误 {e.status_code}: {e.message}")

Node.js — 全面的错误处理

import OpenAI from "openai"

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

try {
  const response = await client.responses.create({
    model: "gpt-5.4",
    input: "你好！",
  })
  console.log(response.output_text)
} catch (error) {
  if (error instanceof OpenAI.APIConnectionError) {
    console.error("无法连接到 API，请检查网络。")
  } else if (error instanceof OpenAI.APIConnectionTimeoutError) {
    console.error("请求超时，请重试或增加超时时间。")
  } else if (error instanceof OpenAI.APIError) {
    switch (error.status) {
      case 401:
        console.error("API Key 无效，请检查凭证。")
        break
      case 429:
        console.error("触发频率限制，请降低请求速率。")
        break
      default:
        if (error.status >= 500) {
          console.error(`服务器错误（${error.status}），请稍后重试。`)
        } else {
          console.error(`API 错误 ${error.status}: ${error.message}`)
        }
    }
  } else {
    throw error
  }
}

最佳实践

始终显式处理错误 — 不要让 API 错误导致应用崩溃，使用 try/catch 包裹所有调用。
记录错误详情 — 记录状态码、错误消息和请求 ID，便于调试排查。
设置超时时间 — 非流式请求使用较短的超时（约 60 秒），流式请求使用较长的超时（约 5 分钟）。
实现熔断机制 — 如果持续收到 5xx 错误，在更长的时间段内暂停请求。
区分错误类型 — 在代码中根据需要分别处理网关错误和上游错误。
监控错误率 — 在应用指标中追踪错误率，以便及早发现问题。

本页目录