错误代码排错
测连失败或聊天气泡报错时，点 查看详情，对照本页的错误代码（或文案关键词）。
详情一般包含：
- 错误代码（英文标识，如
invalidApiKey） - 错误原因
- 尝试修复
下列「代码」以 App 错误详情里展示的名称为准。
快速对照表
| 错误代码 | 用户可见摘要 | 优先处理 |
|---|---|---|
missingApiKey | 请先填写 API 密钥 | 模型连接里填写密钥 |
invalidApiKey | 密钥无效或过期 | 检查复制是否完整；控制台重新生成 |
forbidden | 访问被拒绝 | 权限、模型是否开通 |
regionForbidden | 地区不可用 | 换网络 / 代理 / 国际站 |
network | 网络连接失败 | 网络、Base URL、防火墙 |
timeout | 请求超时 | 网络；本地模型加大超时 |
modelNotFound | 模型不存在 | 核对模型 ID |
modelRetired | 模型已下线 | 从列表改选当前可用模型 |
rateLimit | 过于频繁 | 等待后重试 |
freeTierQuota | 免费档请求配额 | 按 Please retry in … 等待；降低频率或升级付费档 |
insufficientQuota | 额度不足 | 充值 / 换密钥 |
spendingCapExceeded | 月度消费上限 | 控制台提高 spend cap |
providerReturnedError | 上游返回错误 | 换模型 / 避开同厂商 :free / OpenRouter BYOK |
contextLengthExceeded | 上下文超限 | 降记忆；回复令牌设 None；换大上下文模型 |
anthropicMaxTokensRequired | Claude 缺 max_tokens | 模型设置开启「回复令牌」 |
badRequest | 参数有误 | 检查参数与兼容接口格式 |
serverError | 服务端错误 | 稍后重试 |
requestFailed | 请求失败 | 看详情原文 |
contentPolicy | 安全审核未通过 | 重生成 / 换模型 / 改写 |
emptyContent | 回复为空 | 重试；检查思考模型字段 |
modelAtCapacity | 模型满载 | 等待或换模型 |
productNotActivated | 产品未开通 | 控制台开通模型 |
visionUnsupported | 不支持图片 | 换视觉模型或关附图 |
textOutputUnsupported | 不支持文字对话 | 改选文本聊天模型，勿选 TTS/生图专用 ID |
分类详解
missingApiKey
- 现象：未填密钥无法请求。
- 处理：设置 → 模型连接 → 填写 API 密钥。本地 Ollama 等可填占位字符（若校验非空）。
invalidApiKey
- 现象：401 类、密钥无效。
- 处理：无空格完整复制；确认国内/国际站与密钥匹配；重新生成密钥。
forbidden / regionForbidden
- 现象：403、地区限制。
- 处理：确认模型权限；换代理或国际站 Base URL。
network / timeout
- 现象：连不上或长时间无响应。
- 处理：
- 检查 Base URL（本地勿用手机上的
localhost，用电脑局域网 IP）。 - 电脑防火墙放行端口；手机与电脑同一 Wi‑Fi。
- 弱网或本地慢模型：增大超时、换小模型。
- 检查 Base URL（本地勿用手机上的
modelNotFound
- 现象：模型 ID 错误。
- 处理：测连后从列表重选；本地与
ollama list/ LM Studio 显示名一致。
modelRetired
- 现象：HTTP 404，文案含
no longer available to new users/use a newer model（如models/gemini-2.5-flash-lite）。 - 区别：模型已被服务商停用或不再向新用户开放，不是拼写错误。
- 处理：模型连接里拉取最新列表，改选仍在线的 Gemini（如
gemini-flash-latest）。不必改用 Interactions API。目录：Gemini models。
rateLimit
- 处理：降低发送频率；稍后重试；升级套餐。
freeTierQuota
- 现象：Gemini 等返回
HTTP 429+generate_content_free_tier_requests（常见 limit: 20），并提示Please retry in …s。 - 区别：这是免费档每分钟/每天请求次数，不是账户没钱，也不是项目月度 spend cap。
- 处理：等待提示秒数后重试；降低发送频率；到 AI Studio 用量 查看；需要更高限额则开通结算/升级付费档。说明：Gemini rate limits。
insufficientQuota / spendingCapExceeded
- 区别：额度用尽 vs 项目月度消费上限（后者稍后重试通常无效）。
- 处理：充值；或到控制台调整 spend cap（如 Google AI Studio Spend 页）。
providerReturnedError
- 现象：OpenRouter 等返回
HTTP 429: Provider returned error（:free模型常见）。 - 处理：稍后重试；换其他厂商空闲模型；或 OpenRouter BYOK。
contextLengthExceeded
- 处理：设置 → 模型 → 模型设置 → 减小记忆长度；将「回复令牌」设为 None（若适用）；换更大上下文模型。
anthropicMaxTokensRequired
- 处理：Claude 必须带 max_tokens → 模型设置中开启「回复令牌」，不要设为 None。
badRequest
- 处理：检查 temperature 等参数；第三方兼容站是否真兼容 OpenAI/Anthropic 格式。
serverError / requestFailed / modelAtCapacity
- 处理：稍后重试；换端点或模型；持续失败联系服务商并附详情原文。
contentPolicy
- 处理：重生成、改写、换审核更松的模型；部分 NSFW 卡易触发输出拦截。
emptyContent
- 处理：重试；部分思考模型只返回 reasoning → 看详情中的完整字段或换模型。
productNotActivated
- 处理：云厂商控制台开通对应产品/模型后再用当前密钥。
visionUnsupported
- 处理：换支持视觉的模型；或不要发图 / 开启识图描写流程改用纯文本描写。
textOutputUnsupported
- 现象：HTTP 400，文案含
response modalities且TEXT不受支持（如models/gemini-2.5-flash-preview-tts只接受AUDIO）。 - 区别：选了语音合成 / 生图等专用模型做聊天测连，不是密钥或采样参数填错。
- 处理：模型连接里改选文本聊天模型（如
gemini-flash-latest）。不要选名称带tts、image的专用 ID。语音、生图请到对应功能里配置。
本地模型专项
连不上电脑上的 Ollama / LM Studio：见 本地模型排错。
App 测连 / 聊天报错（含错误代码）：见 使用手册 · 错误代码排错。
截图
