常见问题 & 报错指南
欢迎查阅 API 调用常见问题解答。如果您在使用过程中遇到以下报错信息，请参考相应的排查建议进行处理。
1
服务端 & 网络连接类错误
502 Upstream service temporarily unavailable
可能原因
上游服务暂时不可用，或者您的网络连接不稳定；如果您使用的是 1M 上下文模型，可能是因为单次对话上下文超出了 200K 且未能自动压缩。
解决方案
1. 建议您先关闭 VPN（包括 CCSwitch 的代理）并稍等几分钟后重试。可以通过访问 /status 确认 Base URL 的连通性。
2. 检查您的上下文是否超过 200K。如果超出，请新开一个会话，并将模型切换为非 1M 上下文的版本。
Unable to connect API (UND_ERR_SOCKET) 或 (ECONNRESET)
可能原因
本地网络环境异常、代理节点不稳定或被防火墙拦截。
解决方案
首先排查本地网络环境。建议关闭 VPN 或代理节点后重试，或者更换网络环境再次尝试。
Unable to connect API (EAI_AGAIN)
可能原因
客户本地的 DNS 解析出现问题。
解决方案
建议检查本地 DNS 解析是否被污染。您可以在终端执行 dig api.999555999.com 测试域名解析是否正常。
2
账号 & 并发类错误
503 Service Unavailable 或 503 No available accounts
可能原因
当前时段请求量较大，上游服务过载，或当前分组并发数已达上限。
解决方案
服务处于满载状态，建议您稍等几分钟后再次尝试。
429 Upstream rate limit exceeded, please retry later
可能原因
您的请求频率过高，触发了服务端的限流保护机制。
解决方案
建议您暂停请求，稍等几分钟后再试。
3
认证 & 权限类错误
401 API key is required in Authorization header...
可能原因
发起请求时，未正确携带认证所需的 API Key。
解决方案
请检查您的请求代码，确保已在环境变量或 Request Headers 中正确配置了 API Key。
403 API Key is not assigned to any group and cannot be used.
可能原因
您的 API Key 尚未绑定到任何可用分组。
解决方案
请前往控制台检查，并为该 API 密钥正确分配所需的分组。
429 api key 日限额已用完
可能原因
该 API Key 的每日调用额度已经消耗完毕。
解决方案
请前往控制台检查您的 API 密钥额度设置，必要时进行充值或调整日限额。
4
客户端 & 特定环境限制
503 No available accounts: this group only allows Claude Code clients
可能原因
当前您使用的分组/渠道设置了限制，仅允许来自 Claude Code 客户端的调用。
解决方案
请将您的使用环境切换为 Claude Code 客户端进行调用。
使用 CCSwitch 时出现 503 报错
可能原因
触发了仅允许 Claude Code 客户端调用的限制。
解决方案
这不会影响您在 Claude Code 客户端中的正常功能。请确保您在 Claude Code 扩展插件环境中进行使用。