Claude/OpenAI/Gemini/DeepSeek 模型特定报错排查手册（2026）

TL;DR — 模型特定报错和通用 HTTP 错误码是两回事：429/401 有标准解法，但”模型不存在”、“版本迁移 400”、“DeepSeek 402”这类错误需要按平台逐一排查。本文覆盖 Claude、OpenAI、Gemini、DeepSeek 四个平台的模型特定报错，每个错误给出精确原因和修复步骤。

---

调 AI API 遇到报错，大多数人第一反应是搜”429 怎么办”或者”401 怎么解决”。这类通用错误码有标准答案，网上一搜一大把。

但有一类报错不一样：模型名称写错、版本不存在、账户权限不够用某个模型、从旧版本迁移到新版本后代码突然失效。这些错误的错误信息往往很模糊，搜索引擎几乎找不到有用的答案，因为它们和具体的模型版本强绑定。

这篇就专门处理这类问题。通用错误码（429/401/500）的排查方法参见AI API 报错排查完全指南，本文不重复。

模型特定报错的共同特征

先说几个跨平台的共同规律。

“The model does not exist” 可能是拼写错误，也可能是权限问题，错误信息本身不区分这两种情况。同一个模型，在不同平台的调用方式也不同：

• Anthropic 原生 API：claude-opus-4-7（Claude 4.x Opus/Sonnet 无日期后缀；Haiku 保留日期后缀，如 claude-haiku-4-5-20251001）
• ofox 等聚合平台：anthropic/claude-opus-4.7（provider/model 格式）

混用格式是最常见的错误来源。每次大版本升级（Claude 3→4、GPT-4→5）都会引入 breaking changes，旧代码不加修改直接换模型 ID 往往会报错。

---

Claude 模型特定报错

模型 ID 格式错误

报错信息：{"type":"error","error":{"type":"invalid_request_error","message":"model: field required"}}

或者：model: claude-4-sonnet is not supported

Claude 的模型 ID 有严格格式，常见写法错误：

修复：到 Anthropic 官方模型列表 或 ofox 模型页面 复制准确的模型 ID，不要凭记忆写。

Claude 4.x 迁移报错：400 prefill 不再支持

报错信息：400 invalid_request_error: messages: roles must alternate between "user" and "assistant", but found multiple "assistant" roles in a row

或者：Prefilling assistant messages is not supported for claude-sonnet-4-6

Claude 3 允许在 messages 数组末尾放一条 assistant 角色的消息（prefill），用来引导模型输出格式。Claude 4.6 及以上版本取消了这个特性。

# Claude 3 可以这样写（Claude 4.6+ 会报 400）
messages = [
    {"role": "user", "content": "用 JSON 格式回答"},
    {"role": "assistant", "content": "{"}  # prefill，引导 JSON 输出
]

修复：把 prefill 内容移到 system prompt 里：

# Claude 4.6+ 正确写法
system = "请用 JSON 格式回答，直接输出 JSON，不要加 markdown 代码块"
messages = [{"role": "user", "content": "用 JSON 格式回答"}]

claude-opus-4.7 权限不足

报错信息：{"type":"error","error":{"type":"permission_error","message":"Your API key does not have access to this model"}}

Claude Opus 4.7 是 Anthropic 的旗舰模型，需要账户达到一定消费门槛才能访问。新注册账户或低消费账户默认只能用 Sonnet 和 Haiku。

排查步骤：登录 Anthropic Console → Settings → Limits，查看当前 Usage Tier。Tier 1 以上才能访问 Opus 系列。如果急需使用，通过 ofox 等聚合平台调用，不受单账户 Tier 限制。

上下文窗口超限（模型版本差异）

报错信息：413 request_too_large: Your request exceeds the maximum allowed number of bytes

或者：400 invalid_request_error: prompt is too long: 210000 tokens > 200000 maximum

不同 Claude 版本的上下文窗口不同：Claude Opus 4.7 / Sonnet 4.6 / Haiku 4.5 都是 200K tokens，但 Haiku 的实际可用输入略小。从 Sonnet 切换到 Haiku 时，如果 prompt 接近 200K，可能因为这个差异报错。

修复：用 tiktoken 或 Anthropic 的 token 计数 API 在发送前检查长度，超限时截断或分段处理。

---

OpenAI 模型特定报错

模型不存在或无访问权限

报错信息：The model 'gpt-5' does not exist or you do not have access to it

这是 OpenAI 最常见的模型特定报错，原因有两种，错误信息不区分。

模型 ID 拼写错误：

账户 Tier 不够：GPT-5.4 Pro 需要 Tier 3 以上，GPT-5.4 需要 Tier 2 以上。新账户默认 Tier 1，只能访问部分模型。排查方法：OpenAI 后台 → Settings → Limits → 查看 “Model access” 列表。

已弃用模型

报错信息：The model 'gpt-4-0314' has been deprecated

OpenAI 会定期弃用旧版本模型，弃用后调用返回 404 或 400。到 OpenAI 模型弃用页面 查看迁移建议。如果代码里硬编码了带日期的模型 ID（如 gpt-4-0613），改用不带日期的别名（如 gpt-4），OpenAI 会自动路由到最新稳定版本。

GPT-5.4 的 TPM 限制

GPT-5.4 的 TPM（每分钟 Token 数）限制相对于其能力来说偏低，尤其是 Tier 1/2 账户。长 prompt + 长输出的场景很容易触发 429，但原因是 TPM 而不是 RPM。

错误信息里会明确说明：Rate limit reached for gpt-5.4 in organization xxx on tokens per min (TPM): Limit 40000, Used 38000, Requested 5000

修复：减少 prompt 长度，或者用 max_tokens 限制输出长度，或者升级 Tier。

---

Gemini 模型特定报错

RESOURCE_EXHAUSTED vs QUOTA_EXCEEDED

Gemini API 的限流报错有两种，处理方式完全不同。

RESOURCE_EXHAUSTED（速率限制）：

{
  "error": {
    "code": 429,
    "message": "Resource has been exhausted (e.g. check quota).",
    "status": "RESOURCE_EXHAUSTED"
  }
}

这是 RPM/TPM 速率限制，等几秒到几分钟会自动恢复。加指数退避重试即可。

QUOTA_EXCEEDED（配额耗尽）：

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'generate_content_free_tier_requests'",
    "status": "RESOURCE_EXHAUSTED"
  }
}

两种错误的 HTTP 状态码都是 429，但 message 里会提到 quota。这是每日配额耗尽，需要等到次日 UTC 0 点重置，或者升级付费计划。Gemini 2.5 Pro 免费 Tier 每日限 100 次请求（RPD），开发测试很容易触发。

模型名称格式

Gemini 的模型 ID 格式在 2025 年底有过调整：

通过 ofox 调用时统一用 google/gemini-3.1-pro-preview 格式，不需要记带日期的版本号。

区域限制

Gemini API 在部分地区不可用，国内直连会返回：

403 User location is not supported for the API use

这不是模型问题，是地区限制。通过 ofox 等国内可访问的聚合平台调用，无需代理。

---

DeepSeek 模型特定报错

DeepSeek 的错误码体系和 OpenAI 有差异，有几个独特的错误码值得单独说。

402 余额不足（DeepSeek 特有）

报错信息：{"error":{"message":"Insufficient Balance","type":"insufficient_balance_error","code":402}}

DeepSeek 采用严格的预付费模式，余额归零后立即停止服务，不像 OpenAI 有信用额度缓冲期。402 是 DeepSeek 特有的错误码，标准 HTTP 协议里 402 是”Payment Required”，DeepSeek 直接用了这个语义。

修复：登录 DeepSeek 平台 充值。如果需要统一管理多个平台的余额，可以通过 ofox 调用 DeepSeek 模型（deepseek/deepseek-v3.2），只需维护一个账户余额。

422 参数无效

报错信息：{"error":{"message":"Invalid Parameters","type":"invalid_request_error","code":422}}

DeepSeek 用 422 表示参数无效，而 OpenAI 用 400。常见触发场景：

• temperature 超出范围（DeepSeek 要求 0-2，部分旧代码设了 2.5）
• max_tokens 超过模型上限
• messages 格式不符合 OpenAI 兼容规范（DeepSeek 声称兼容 OpenAI 格式，但有细微差异）

排查：检查请求参数是否在 DeepSeek API 文档 规定的范围内。

模型名称：V3.2 vs V4

DeepSeek 的版本命名有些混乱。目前 ofox 上架的是 deepseek/deepseek-v3.2，这对应 DeepSeek 官方的 deepseek-chat 端点（指向最新稳定版）。

如果你在代码里写了 deepseek-v4 或 deepseek/deepseek-v4，会返回模型不存在的错误。通过 ofox 调用时，用 deepseek/deepseek-v3.2 是当前正确写法。

---

用 ofox 统一管理多模型

上面这些报错，有相当一部分是因为直接对接各平台原生 API 导致的：每个平台的模型 ID 格式不同、认证方式不同、错误码体系不同。

通过 ofox 这类聚合平台调用时，可以规避很多模型特定的麻烦：统一模型 ID 格式（provider/model-name，不需要记各平台的日期后缀）、一个 API Key 管所有平台、不会因为某个平台余额归零而中断（DeepSeek 402 问题）、Gemini 的区域限制问题自动解决。

配置方式：把 base_url 改为 https://api.ofox.ai/v1，api_key 换成 ofox 的 Key，其余代码不变。

from openai import OpenAI

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

# 调用 Claude Opus 4.7
response = client.chat.completions.create(
    model="anthropic/claude-opus-4.7",
    messages=[{"role": "user", "content": "Hello"}]
)

---

快速对照表

---

通用错误码（429/401/500）的详细排查方法参见AI API 报错排查完全指南。Claude 特定错误的深度排查参见 Claude API 报错汇总。如果你在用 AI 编程工具（Cursor、Claude Code、Roo Code），工具层面的报错参见 AI 编程工具报错完全指南。