ERROR CODES / 110 PAGES
报错百科，先查再换。
110 个 AI API 错误码：一句话结论、按排查成本排序的成因、分场景修法、责任判定。搜索错误码或报错原文。
110 条
4xx · 请求或权限
49 条403403 Forbidden：权限不足 / 地区受限怎么解决403 的三种成因：地区封锁、账号未激活、模型未授权。附出口 IP 检测和权限确认方法。429429 Too Many Requests：请求太频繁怎么解决429 限速的完整排查：区分是你自己请求太快、中转站分组限流，还是上游整体过载，附可复制的退避重试代码。400max_tokens 超出模型上限：怎么调max_tokens 大于模型最大输出导致的 400，附各模型输出上限对照。，附原因排序、修复步骤与责任判定。413Anthropic 413 Request too large：请求体太大Anthropic 请求体超限的处理：图片/PDF 太大、一次塞太多消息。，附原因排序、修复步骤与责任判定。400Claude API Error 400：请求格式错误怎么解决400 参数错误的排查顺序：缺 max_tokens、messages 结构不对、模型不支持该参数，附最小可复现请求。401百度千帆报错：Access Token 过期百度千帆的 access_token 机制与过期处理。，附原因排序、修复步骤与责任判定。401Cline API key is required：Key 未配置Cline 插件没读到 API Key 的常见原因与配置方法，含 Provider 选择、Key 存放位置和在 VS Code 里重新配置的步骤。401Codex please re-run codex login：登录态失效Codex CLI 登录态失效的处理，含 token 位置、多设备冲突、代理影响。400Gemini Content blocked：内容被安全策略拦截Gemini 返回 Response was blocked 的原因与处理，含 safety setting 调整与提示词改写。400context_length_exceeded：上下文超长怎么解决上下文超限的四种修法：裁剪历史、摘要化、分段处理、换长窗口模型，附 token 估算方法。402Credit balance is too low：余额不足怎么解决Anthropic Console 余额不足的判定与充值路径，以及和订阅套餐的区别。401Cursor session expired：登录态假死Cursor 登录态失效但界面还显示已登录的处理：退出重登、清缓存、换网络，以及判断是不是账号被踢下线。429Cursor Usage limit 已达上限Cursor 用量上限的判定：订阅额度、API 计费切换、重置周期，附切换到自己 API Key 的具体步骤。401DeepSeek 401 Unauthorized：认证失败DeepSeek 平台 Key 无效的排查。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。429DeepSeek 429 限流：怎么错峰DeepSeek 高峰期限流的特征与处理方式。，附退避重试策略与责任判定表。数据来自实测，结论可复核。400Gemini API key not valid：Key 无效怎么办Google AI Studio 的 Key 无效排查：Key 类型、项目是否启用 API、地区。401Gemini CLI authentication error：登录认证失败Gemini CLI 认证失败的排查：OAuth 授权失败、API Key 模式冲突、地区限制。429Gemini 429 quota exceeded：配额超限怎么处理Gemini 免费层与付费层的配额差异、重置周期与升配方式。，附原因排序、修复步骤与责任判定。400Gemini 地区不支持：User location is not supportedGemini 对部分地区不开放，报 location 错误。判断与绕开方式。，附原因排序、修复步骤与责任判定。400Gemini 工具调用返回参数错误Gemini function calling 的参数结构问题：schema 不合法、缺必填、类型不匹配。429Groq 429 Rate limit：免费层限制怎么算Groq 免费层的速率限制规则与处理。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。400图片输入报错：模型不支持视觉给纯文本模型传了图片导致的 400，附支持视觉的模型判断方法。，附原因排序、修复步骤与责任判定。402DeepSeek 402 Insufficient Balance：余额不足DeepSeek 账户余额不足的判定、充值路径与免费额度说明，附 402 与限流、Key 无效的区分方法。402insufficient_quota：额度用完了怎么办额度不足的排查：查账户余额、配额窗口重置时间、充值层级，以及免费额度和付费额度的区别。401401 invalid_api_key：API Key 无效怎么解决401 认证失败的九种原因排序：Key 复制带空格、环境变量名错、用了测试 Key、Key 被禁用，附逐条验证方法。422422 Invalid parameters：参数校验不通过国产模型常见 422 参数错误的排查：字段名不匹配、缺少必填项、类型错误，附最小可复现请求。401Claude Code Login expired：登录态失效怎么解决Claude Code 提示 Please run /login 或 Login expired 的原因与修法，含 token 过期、多账号冲突、配置文件损坏三种情况。400消息角色错误：role 不合法messages 里 role 用了不支持的值，或首条是 assistant。，附原因排序、修复步骤与责任判定。400MiniMax 报错：GroupId 与模型名MiniMax 开放平台的 GroupId、模型名与鉴权错误。，附原因排序、修复步骤与责任判定。404model_not_found：模型不存在怎么解决404 模型不存在的排查：模型 ID 大小写、分隔符、中转站命名映射，附拉取模型列表的方法。400月之暗面 Kimi 报错：常见问题Kimi 开放平台的认证、模型与限流错误处理。，附原因排序、修复步骤与责任判定。401OpenAI 401 Incorrect API key：Key 错在哪OpenAI 401 的排查顺序：项目 Key 与用户 Key、前缀、复制空格、组织权限。429OpenAI billing hard limit reached：达到消费上限OpenAI 账户设置了硬性消费上限，达到后所有请求被拒。怎么调整或解除。，附原因排序、修复步骤与责任判定。400OpenAI JSON mode 报错：输出不是合法 JSON开了 JSON 模式仍然报解析失败的原因：没写 json 关键字、schema 不严、模型不支持。403OpenAI 项目 Key 没有模型权限项目 Key 默认只对部分模型开放，调用未授权模型会报权限错误。，附原因排序、修复步骤与责任判定。400OpenAI Responses API 报错：和 Chat Completions 的区别用 Responses API 时常见的参数结构错误，附两种接口的字段对照。，附原因排序、修复步骤与责任判定。403organization disabled：组织被停用OpenAI 组织被停用的常见原因与申诉路径，含风控触发条件和换账号时的合规注意事项。400通义千问 DashScope 报错：常见错误对照阿里云百炼 / DashScope 的常见错误码与处理：Key、模型名、配额。，附原因排序、修复步骤与责任判定。403403 Rate limit：403 却提示限流有些站点用 403 表达限流而不是权限，容易误判。附识别方法、快速验证步骤和换分组的判断依据。400硅基流动 SiliconFlow 报错SiliconFlow 的认证、模型与额度错误处理。，附原因排序、修复步骤与责任判定。495SSL 证书验证失败：CERTIFICATE_VERIFY_FAILED证书校验失败的排查：自签证书、证书过期、中间人代理、系统时间不同步，附逐项验证方法。400stream 参数不支持：非流式兜底某些接口/模型不支持流式，或中转站没实现流式转发。，附超时设置与断线重连处理。数据来自实测，结论可复核。400temperature 参数不合法：范围与兼容性temperature 取值超出 [0,2] 或推理模型不支持该参数导致的报错。400腾讯混元报错：SecretId / SecretKey 配置腾讯云混元的鉴权方式与常见错误。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。400tool_calls 结构校验失败函数调用返回结构不合法导致的报错，含空数组、缺 id、arguments 不是 JSON 字符串。400unsupported parameter：推理模型不支持参数推理模型（o1/o3/deepseek-reasoner）不接受 temperature 等参数导致的 400。429Claude Code Usage limit reached：用量上限怎么解决Claude Code 订阅用量上限（session/weekly limit）的判定与恢复时间，以及怎么换 API 计费。400火山方舟 Ark 报错：endpoint 与模型 ID火山引擎方舟的常见错误：推理接入点 ID、模型 ID、鉴权方式。，附原因排序、修复步骤与责任判定。400智谱 GLM 报错：Key、模型与并发限制智谱开放平台的常见错误：认证、模型不存在、并发超限。，附原因排序、修复步骤与责任判定。
5xx · 服务端或上游
7 条500Anthropic 500 internal server errorAnthropic 返回 500 的处理与判断：临时故障、账号问题、请求体异常。503无可用渠道：中转站特有错误全解「无可用渠道」「当前分组下没有可用渠道」的成因与处理，这是中转站引擎（new-api/one-api）特有错误。500OpenAI 500 The server had an error：服务端错误OpenAI 500 服务端错误的处理：重试策略、换模型验证、判断是否影响全部账号，以及什么时候该等。529529 Overloaded：上游过载是什么，怎么解决Anthropic 529 overloaded 的含义与处理：供应商容量满了，跟你的 Key 无关。什么时候该等、什么时候该换渠道。502中转站 502 Bad Gateway502 的成因：上游不可达、站点网关故障、超时。，附真假判断、计费核对与换站建议。504中转站 504 Gateway Timeout504 与 502 的区别，以及长请求时的处理方法。，附真假判断、计费核对与换站建议。503中转站「无可用渠道」：站点侧问题无可用渠道的成因：渠道全故障、分组没配、模型未映射。，附真假判断、计费核对与换站建议。
客户端 / 配置 / 网络
54 条客户端Aider 连接模型失败Aider 的命令行模型配置与 API Key 环境变量。，附原因排序、修复步骤与责任判定。流式Claude 流式响应中途断开：怎么排查流式输出到一半断开的原因：网关超时、心跳缺失、客户端缓冲。，附超时设置与断线重连处理。自部署AnythingLLM 模型连接报错AnythingLLM 的 LLM 提供商配置与常见错误。，附原因排序、修复步骤与责任判定。客户端Chatbox 连接失败：API 配置排查Chatbox 添加自定义 API 后的常见错误。，附原因排序、修复步骤与责任判定。客户端Cherry Studio 报错：模型连接失败Cherry Studio 添加服务商后连不上的排查。，附原因排序、修复步骤与责任判定。配置Claude Code 配了 Base URL 不生效：还是走官方ANTHROPIC_BASE_URL 设了但请求仍发到官方，常见于变量名拼错、shell 配置没 source、客户端覆盖。环境claude: command not found：命令找不到怎么办Claude Code 安装后命令不可用的排查：PATH 没生效、npm 全局目录不对、nvm 版本切换丢失。上下文Claude Code 提示上下文快满：怎么清理Claude Code 上下文接近上限时的处理：/compact、清历史、拆分任务。MCPClaude Code MCP 启动超时：工具加载不出来MCP server 启动超时的处理：冷启动慢、npx 下载、命令路径错。，附配置校验与返回值处理建议。登录Claude Desktop 登录失败：卡在登录页Claude Desktop 登录异常的排查：网络、账号地区、缓存。，附登录态、订阅与地区限制排查。配置Cline 配置 Provider 报错：连不上模型Cline 选错 Provider 或 Base URL 格式不对导致的连接失败。工具Cline 工具执行失败：命令或文件操作被拒Cline 执行终端命令/写文件失败的权限与配置问题。，附配置校验与返回值处理建议。安装Codex CLI 安装失败：npm 报错怎么办Codex CLI 安装时的常见错误：权限、Node 版本、镜像源。，附环境检查步骤与常见失败原因。配置Codex 沙箱错误：命令被拦截Codex 在沙箱里执行命令被拒的处理：权限模式、目录范围、系统差异。，附原因排序、修复步骤与责任判定。ECONNREFUSEDUnable to connect to API：连接失败怎么解决ECONNREFUSED / ECONNRESET / ENOTFOUND 三种连接错误的区别与排查，含 Base URL 常见写法错误。配置Continue 插件配置不生效Continue 的 config.json 写错导致模型不可用或报错。，附原因排序、修复步骤与责任判定。EXTENSIONCursor 插件冲突：补全不工作装了多个 AI 编码插件导致冲突，Cursor 的补全或对话失效。，附原因排序、修复步骤与责任判定。模型Cursor 里模型显示不可用Cursor 模型列表灰掉或报模型不可用的原因：套餐限制、地区、自定义 API。网络Cursor 提示网络错误 / 无法连接Cursor 连不上服务的排查：代理、防火墙、公司网络、DNS。，附原因排序、修复步骤与责任判定。自部署Dify 接入自定义模型报错Dify 的 OpenAI-API-compatible 插件配置错误。，附原因排序、修复步骤与责任判定。网络DNS 解析失败或被污染域名解析异常的处理：换 DNS、改 hosts、DoH。，附原因排序、修复步骤与责任判定。ECONNRESET流式响应 ECONNRESET：连接被重置流式传输中被 RST 的排查：中间设备、超时、负载。，附超时设置与断线重连处理。自部署FastGPT 模型配置报错FastGPT 接入外部模型的配置与错误处理。，附原因排序、修复步骤与责任判定。工具工具调用死循环：模型反复调用同一个工具函数调用陷入循环的原因：工具返回格式错、模型理解偏、缺少终止条件。，附配置校验与返回值处理建议。环境Gemini CLI 装不上 / 命令找不到Gemini CLI 安装与 PATH 配置的排查。，附原因排序、修复步骤与责任判定。内容安全Gemini 内容被安全策略拦截（finishReason SAFETY）Gemini 返回 SAFETY 或 blocked 的处理：safetySettings 调整与提示词改写。网络HTTP/2 协议错误（ERR_HTTP2_PROTOCOL_ERROR）HTTP/2 协商失败或中间层不支持导致的连接错误。，附原因排序、修复步骤与责任判定。客户端沉浸式翻译 AI 翻译报错沉浸式翻译接入自定义 API 的常见错误。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。客户端JetBrains AI Assistant 报错JetBrains 系 IDE 的 AI 助手连接问题。，附原因排序、修复步骤与责任判定。客户端LobeChat 自部署连不上模型LobeChat 环境变量配置错误导致模型不可用。，附原因排序、修复步骤与责任判定。MCPMCP 配置格式错误：服务起不来Claude Code / Cursor 的 MCP 配置文件写错导致加载失败。环境MCP server 报 Node / npx 不存在MCP 依赖 Node 或 Python 运行时缺失导致启动失败。，附原因排序、修复步骤与责任判定。MCPMCP server failed to connect：MCP 连接失败Claude Code / Cursor 的 MCP 服务器连接失败排查：命令路径、权限、启动超时。额度中转站「额度不足 / 余额不足」中转站账户额度用尽的判断与充值。，附真假判断、计费核对与换站建议。数据来自实测，结论可复核。中转站中转站「令牌无效 / 无效的令牌」new-api / one-api 系中转站令牌错误的排查。，附真假判断、计费核对与换站建议。客户端NextChat 配置自定义接口报错NextChat 的自定义接口地址与模型名配置问题。，附原因排序、修复步骤与责任判定。客户端Obsidian AI 插件报错Obsidian 的 AI 插件配置模型失败的排查。，附原因排序、修复步骤与责任判定。ECONNREFUSEDFailed to connect to Ollama：本地模型连不上Ollama 连不上的排查：服务未启动、端口不对、跨容器网络配置，附手动验证命令。自部署Open WebUI 连接外部模型失败Open WebUI 的 OpenAI 兼容连接配置与常见错误。，附原因排序、修复步骤与责任判定。流式OpenAI 流式连接被断开（stream disconnected）OpenAI 流式输出中断的原因与重试策略。，附超时设置与断线重连处理。数据来自实测，结论可复核。网络配了代理但请求还是直连代理配置不生效的排查：环境变量、应用级代理、PAC。，附环境变量与链路验证方法。账号中转站账号被封 / 无法登录站点封号的常见原因与处理，以及如何避免。，附真假判断、计费核对与换站建议。数据来自实测，结论可复核。中转站怀疑中转站「掺假」：怎么验证模型真假判断中转站是否用廉价模型冒充高价模型的几种可操作验证方法。，附真假判断、计费核对与换站建议。中转站中转站模型名映射错乱站点把模型名映射错，导致「模型不存在」或返回的不是你要的模型。，附真假判断、计费核对与换站建议。计费中转站标价和实际扣费不一致倍率、分组、缓存计价导致的账单差异，怎么核对。，附真假判断、计费核对与换站建议。跑路中转站突然无法访问：跑路判断站点打不开时的判断流程：真挂了、换域名、还是跑路。，附真假判断、计费核对与换站建议。客户端Roo Code 报错：模型或工具异常Roo Code 的 Provider 配置与工具执行错误处理。，附配置校验与返回值处理建议。性能首 token 很慢：不是报错但要优化首字延迟高的原因与客户端感知优化。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。超时API Error: The operation timed out：请求超时怎么解决AI API 超时的五种原因：客户端阈值太短、上游高负载、网络链路、代理丢连接、网关误报，附参数调整与判断表。中转站token 计数对不上：为什么算的比实际少tokenizer 差异导致预估与实际不符，附估算方法和留余量建议。，附原因排序、修复步骤与责任判定。工具工具返回内容过大导致上下文爆掉工具返回巨量文本把上下文撑爆的处理。，附配置校验与返回值处理建议。数据来自实测，结论可复核。客户端GitHub Copilot 报错：无法使用Copilot 的登录、订阅与网络问题。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。客户端Windsurf 登录或模型报错Windsurf 的账号与模型可用性问题。，附登录态、订阅与地区限制排查。数据来自实测，结论可复核。客户端Zed 编辑器 AI 功能报错Zed 的 AI 助手配置与错误处理。，附原因排序、修复步骤与责任判定。数据来自实测，结论可复核。
错误码定义来自官方文档与真机复现；排查顺序是编辑整理，不是官方结论。没有样本的百分比不写。