Question 1

502 Upstream service temporarily unavailable

Accepted Answer

原因：上游服务暂时不可用，或网络连接不稳定；若使用 1M 上下文模型，可能是单次对话上下文超出 200K 且未能自动压缩。解决方案：1. 先关闭 VPN（含 CCSwitch 代理）并稍等几分钟后重试，可访问 /status 确认 Base URL 连通性。2. 检查上下文是否超过 200K，若超出请新开会话并切换为非 1M 上下文版本。

Question 2

Unable to connect API (UND_ERR_SOCKET) 或 (ECONNRESET)

Accepted Answer

原因：本地网络环境异常、代理节点不稳定或被防火墙拦截。解决方案：先排查本地网络环境，建议关闭 VPN 或代理节点后重试，或更换网络环境再次尝试。

Question 3

Unable to connect API (EAI_AGAIN)

Accepted Answer

原因：本地 DNS 解析出现问题。解决方案：检查本地 DNS 是否被污染，可在终端执行 dig ddshub.cc 测试域名解析是否正常。

Question 4

503 Service Unavailable 或 503 No available accounts

Accepted Answer

原因：当前时段请求量较大，上游服务过载，或当前分组并发数已达上限。解决方案：服务处于满载状态，建议稍等几分钟后再次尝试。

Question 5

429 Upstream rate limit exceeded, please retry later

Accepted Answer

原因：请求频率过高，触发了服务端的限流保护机制。解决方案：暂停请求，稍等几分钟后再试。

Question 6

401 API key is required in Authorization header

Accepted Answer

原因：发起请求时未正确携带认证所需的 API Key。解决方案：检查请求代码，确保已在环境变量或 Request Headers 中正确配置 API Key。

Question 7

403 API Key is not assigned to any group and cannot be used.

Accepted Answer

原因：API Key 尚未绑定到任何可用分组。解决方案：前往控制台为该 API 密钥正确分配所需的分组。

Question 8

429 api key 日限额已用完

Accepted Answer

原因：该 API Key 的每日调用额度已消耗完毕。解决方案：前往控制台检查 API 密钥额度设置，必要时充值或调整日限额。

Question 9

503 No available accounts: this group only allows Claude Code clients

Accepted Answer

原因：当前分组/渠道设置了限制，仅允许来自 Claude Code 客户端的调用。解决方案：将使用环境切换为 Claude Code 客户端进行调用。

Question 10

使用 CCSwitch 时出现 503 报错

Accepted Answer

原因：触发了仅允许 Claude Code 客户端调用的限制。解决方案：这不会影响在 Claude Code 客户端中的正常功能，请确保在 Claude Code 扩展插件环境中使用。

FAQ & Troubleshooting

Server & Network Connection Errors

Account & Concurrency Errors

Authentication & Permission Errors

Client & Environment Restrictions