API 连不上：密钥配置的常见错误

症状一：同步模型列表失败

• 密钥填错：复制时带空格、少字符是最常见原因，重新粘贴一遍；
• 协议不对：自定义端点选错了协议（该选 OpenAI 兼容却选了 Anthropic），同步必失败，回自定义端点核对；
• 网络不通：设备无法访问该端点——国内直连部分海外提供商不通，需要配网络代理；
• Base URL 错误：地址多写少写都会指向不存在的地方，注意 v1.3.7 起自定义 OpenAI 端点的 /v1 后缀会自动处理，别手动画蛇添足。

症状二：能同步，发消息报错

• 模型未启用或选错：底栏选的模型在所选提供商下不存在（多提供商用户易犯），回同步模型核对启用清单；
• 活跃密钥不对：多密钥用户检查单选按钮选中的是哪把，见管理多个密钥；
• 权限不足：部分模型需要服务商侧开通特定权限（如推理模型、超长上下文），去服务商后台确认。

症状三：报余额/限额类错误

• 密钥本身没额度或已用完——应用只是转述服务商的回应，充值或换号（多密钥切换就在这时候派上用场）；
• 服务商侧限流（每分钟请求数），稍等重试。

通用三步法

1. 换证法：把怀疑的变量换掉重试——换密钥、换模型、关代理，一次换一个；
2. 对照法：同样密钥在别的客户端或服务商官方控制台里试通，隔离问题在应用侧还是账号侧；
3. 读原文：报错信息通常是服务商原样返回的，错误码直接按服务商文档查，比通用教程准。

相关页面

• 第一把密钥的标准流程，见添加第一个 API 密钥；
• 请求实际发往哪里，见隐私边界。