常见问题

以下问题与具体服务商无关，适用于任何兼容网关。

想按状态码系统排查，看错误码与排障。

还没装好，或者不知道怎么下手？

这一页按状态码整理，适合已经能发出请求、但想查具体错误的情况。

如果你完全不懂命令行、还没配好，或者不知道该把报错发给谁，先看配置失败怎么办。

返回 401 Unauthorized

1. 确认 Key 完整复制，没有多余空格或换行。
2. 确认请求头是 Authorization: Bearer sk-xxx。
3. 确认密钥未过期、未被禁用、额度未用尽。
4. 用 curl 直接验证，排除工具自身的配置问题。

curl https://your-gateway.example.com/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

详见错误码与排障。

返回 403 Forbidden

• 密钥有效但当前分组、IP 或模型没有权限；先用 /v1/models 判断是全部接口失败还是只有某个模型失败。
• 如果所有模型都失败，优先检查分组权限和账户是否被禁用；如果只有特定模型失败，检查密钥的模型限制和分组可用模型。
• 如果错误信息提到 IP 或白名单，核对网关实际看到的出口 IP；代理、CDN 或公司网络可能改变来源 IP。
• 如果响应没有说明原因，记录请求时间、模型、端点和完整错误 body，交给服务方区分权限类型。

详见错误码与排障。

返回 429 Too Many Requests

• 429 表示限流，不代表 Key 无效；优先查看响应是否带 Retry-After。
• 没有 Retry-After 时，使用带抖动的指数退避，不要立即循环重试。
• 降低并发、减少短时间内重复请求；如果只有某个模型触发，可能是模型级限制。
• 持续出现时，记录时间范围、模型和并发量，联系服务方确认限额。

详见错误码与排障。

返回 5xx 或 Anthropic 529

• 500、502、503、504 可能是网关或上游临时故障；529 常见于 Anthropic 过载，部分网关也可能映射成 429 或 503。
• 先短暂退避后重试一次；持续复现时不要无限重试，换模型或渠道验证是否与单个上游有关。
• 流式请求已经输出部分内容后，不要盲目自动重试，先确认是否会重复计费。
• 报障时提供请求时间、模型、端点、HTTP 状态和完整错误 body。

详见错误码与排障。

额度不足，或余额还有但请求被拒绝

• 账户余额和单个 Key 的令牌额度是两套限制；账户还有余额，不代表当前 Key 的额度没有用尽。
• 令牌额度用尽通常返回 401 或 403，具体状态码和 code 以网关实际返回为准。
• 如果启用了预扣或并发请求，可用余额可能被暂时占用；需要以服务商账单和请求日志为准。
• 充值或调高额度后，确认是否需要重新启用或重建 Key；不同服务商行为可能不同。
• 记录 insufficient_user_quota 等错误码和 request ID，便于服务方定位。

详见错误码与排障和概念说明。

上下文超限

• 常见错误码包括 context_length_exceeded，HTTP 状态可能是 400，部分网关可能映射为 413。
• 缩短上下文、减少输出上限、删除不必要的历史消息或附件，再重试。
• 不同模型的上下文窗口和最大输出不同；/v1/models 不保证返回这些限制。
• 如果必须使用长上下文，换用支持更长上下文的模型，或向服务方确认实际限制。

详见模型与能力和错误码与排障。

流式请求中断

• 如果客户端在固定总时长后中断，通常是总超时；如果只在长时间没有新数据时中断，通常是空闲超时。具体行为取决于客户端和网关。
• SSE 中断后是否计费、是否退还预扣，取决于服务商的结算规则，必须以账单和请求日志为准。
• 已经输出部分内容时，不要盲目自动重试；这可能创建第二个上游请求并重复计费。
• 先保留 request ID、最后收到的事件、已输出内容和中断时间，再决定重试或报障。

详见错误码与排障和概念说明。

Key 泄漏了怎么办

• 立即在服务方控制台吊销或删除泄漏的 Key，再创建新 Key。
• 从配置文件、环境变量、CI secrets、Shell 历史和日志中删除旧 Key。
• 检查账单与调用日志，确认是否存在异常模型、异常时间或异常来源 IP 的请求。
• 轮换完成后，用新 Key 验证 /v1/models，再更新各工具配置。
• 不要把 Key 提交到 Git、截图或粘贴到公开 issue；报障时只提供脱敏后的片段。

详见概念说明。

代理或自定义 CA

• 先确认 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 是否被当前工具读取；不同工具和环境变量的支持范围可能不同。
• 公司代理或自签证书可能导致 TLS 校验失败，需要按工具文档配置自定义 CA，而不是关闭所有证书校验。
• 用同一终端直接执行 curl 或工具自带诊断命令，判断是工具配置、代理还是证书问题。
• 如果代理会改变出口 IP，同时检查 IP 白名单是否仍然匹配。

详见错误码与排障。

模型列表不返回能力与价格

• /v1/models 通常只返回模型 ID、对象类型、创建时间和归属等基础字段。
• 模型列表不保证包含上下文窗口、工具调用、视觉、推理、流式支持或价格。
• 能力、限制和计费请以服务商控制台、模型文档和实际测试为准。
• 先用最小请求验证基本对话，再逐步测试工具调用、图片和长上下文等能力。

详见模型与能力和选择接入方式。

同一个 Key 能否走多种协议？

• 取决于网关实现和 Key 的权限；同一个 Key 可能支持 Chat Completions、Responses 和 Anthropic Messages，也可能只支持其中一种。
• 协议是否可用与模型是否可用是两件事；某个模型能在 Chat Completions 调用，不代表也能走 Anthropic Messages。
• 不同协议可能使用不同的路径、认证头和参数格式，配置前先看选择接入方式。
• 用每个协议的最小请求分别验证；如果某个协议返回 404 或 400，先确认网关是否暴露该入口。

详见选择接入方式和模型与能力。

返回 404 Not Found

• Base URL 写错，或带了多余路径。
• 服务不支持该协议入口。
• 工具自动拼接了重复的 /v1。

详见错误码与排障。

模型不存在

调用 /v1/models 拿到真实可用的模型名，再填回配置。注意模型不存在通常返回 503，不是 404。

详见模型与能力和错误码与排障。

请求超时

• 检查本机网络与代理设置。
• 换一个模型或渠道重试，排除上游问题。
• 若只有长请求超时，考虑调大工具的超时配置。
• 流式请求还要区分总超时和空闲超时，见流式请求中断。

详见错误码与排障。

费用与用量对不上

在服务商的日志或账单页面按时间范围筛选，核对每次请求的输入、输出、缓存与费用明细。 本文档不假定你使用某个特定平台，具体入口请参考你所用服务的文档。

详见概念说明和错误码与排障。