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