错误代码排错

测连失败或聊天气泡报错时，点 查看详情，对照本页的错误代码（或文案关键词）。

详情一般包含：

• 错误代码（英文标识，如 invalidApiKey）
• 错误原因
• 尝试修复

下列「代码」以 App 详情里展示的分类名为准（对应 i18n llmTestError.*）。

---

快速对照表

错误代码	用户可见摘要	优先处理
missingApiKey	请先填写 API 密钥	模型连接里填写密钥
invalidApiKey	密钥无效或过期	检查复制是否完整；控制台重新生成
forbidden	访问被拒绝	权限、模型是否开通
regionForbidden	地区不可用	换网络 / 代理 / 国际站
network	网络连接失败	网络、Base URL、防火墙
timeout	请求超时	网络；本地模型加大超时
modelNotFound	模型不存在	核对模型 ID
rateLimit	过于频繁	等待后重试
insufficientQuota	额度不足	充值 / 换密钥
spendingCapExceeded	月度消费上限	控制台提高 spend cap
contextLengthExceeded	上下文超限	降记忆；回复令牌设 None；换大上下文模型
anthropicMaxTokensRequired	Claude 缺 max_tokens	模型设置开启「回复令牌」
badRequest	参数有误	检查参数与兼容接口格式
serverError	服务端错误	稍后重试
requestFailed	请求失败	看详情原文
contentPolicy	安全审核未通过	重生成 / 换模型 / 改写
emptyContent	回复为空	重试；检查思考模型字段
modelAtCapacity	模型满载	等待或换模型
productNotActivated	产品未开通	控制台开通模型
visionUnsupported	不支持图片	换视觉模型或关附图

---

分类详解

missingApiKey

• 现象：未填密钥无法请求。
• 处理：设置 → 模型连接 → 填写 API 密钥。本地 Ollama 等可填占位字符（若校验非空）。

invalidApiKey

• 现象：401 类、密钥无效。
• 处理：无空格完整复制；确认国内/国际站与密钥匹配；重新生成密钥。

forbidden / regionForbidden

• 现象：403、地区限制。
• 处理：确认模型权限；换代理或国际站 Base URL。

network / timeout

• 现象：连不上或长时间无响应。
• 处理：
  • 检查 Base URL（本地勿用手机上的 localhost，用电脑局域网 IP）。
  • 电脑防火墙放行端口；手机与电脑同一 Wi‑Fi。
  • 弱网或本地慢模型：增大超时、换小模型。

modelNotFound

• 现象：模型 ID 错误。
• 处理：测连后从列表重选；本地与 ollama list / LM Studio 显示名一致。

rateLimit

• 处理：降低发送频率；稍后重试；升级套餐。

insufficientQuota / spendingCapExceeded

• 区别：额度用尽 vs 项目月度消费上限（后者稍后重试通常无效）。
• 处理：充值；或到控制台调整 spend cap（如 Google AI Studio Spend 页）。

contextLengthExceeded

• 处理：设置 → 模型设置 → 减小记忆长度；将「回复令牌」设为 None（若适用）；换更大上下文模型。

anthropicMaxTokensRequired

• 处理：Claude 必须带 max_tokens → 模型设置中开启「回复令牌」，不要设为 None。

badRequest

• 处理：检查 temperature 等参数；第三方兼容站是否真兼容 OpenAI/Anthropic 格式。

serverError / requestFailed / modelAtCapacity

• 处理：稍后重试；换端点或模型；持续失败联系服务商并附详情原文。

contentPolicy

• 处理：重生成、改写、换审核更松的模型；部分 NSFW 卡易触发输出拦截。

emptyContent

• 处理：重试；部分思考模型只返回 reasoning → 看详情中的完整字段或换模型。

productNotActivated

• 处理：云厂商控制台开通对应产品/模型后再用当前密钥。

visionUnsupported

• 处理：换支持视觉的模型；或不要发图 / 开启识图描写流程改用纯文本描写。

---

服务层错误码（进阶）

底层还可能出现 LlmErrorCode（日志 / 开发向）：

代码	含义
REQUEST_FAILED	非流式 HTTP 失败
STREAM_FAILED	流式失败
REQUEST_CANCELLED	用户取消
INVALID_CONFIG	配置无效
GET_MODELS_FAILED	拉模型列表失败
TEST_CONNECTION_FAILED	测连失败
PARSE_FAILED	响应解析失败
UNKNOWN	未分类

用户侧请优先看详情里的分类名（上一节），不必强记本表。

---

本地模型专项

连不上电脑上的 Ollama / LM Studio：见 本地模型排错。

App 测连 / 聊天报错（含错误代码）：见 使用手册 · 错误代码排错。

截图