接入报错与排查
遇到报错时，先看完整的错误提示，再按下面对应情况处理。同一个状态码可能有不同原因。
先检查这 4 项
- 密钥：使用从控制台复制的完整 API 密钥，确认没有多余空格。
- 配置：CC Switch 中已启用正确配置，客户端已重启；手动配置时，地址按对应教程填写。
- 分组与模型：该密钥当前分组支持你正在使用的模型和接入方式。
- 可用额度：账户余额、订阅额度，以及你自己给密钥设置的额度和过期时间。
401：密钥或账户状态
| 错误提示 | 怎么处理 |
|---|---|
Invalid API key | 重新从控制台复制完整密钥，确认没有复制缩略内容或多余空格。 |
API_KEY_REQUIRED | 客户端没有正确发送密钥。重新导入并启用配置；使用 SDK 时按对应接口格式传入密钥。 |
API key is disabled | 查看密钥状态，确认是否被你停用。 |
User account is not active | 账户不可用，请联系支持确认。 |
缺少密钥时的完整错误文字
API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header403：权限、分组、余额或有效期
| 错误提示 | 怎么处理 |
|---|---|
Insufficient account balance | 按量余额不足。先在控制台确认余额，再按需要充值。 |
API key 已过期 | 检查密钥的过期时间，更新密钥设置或换用有效密钥。 |
No active subscription found for this group | 检查是否购买了这个分组对应的有效订阅；其他分组的订阅不能直接代替。 |
subscription has expired | 查看“我的订阅”的有效期，需要继续使用时再续订。 |
subscription is suspended | 订阅已暂停，请联系支持确认。 |
API Key 所属分组已停用 / API Key 所属分组已删除 | 在密钥的“选择分组”中改用当前可选、支持目标模型的分组。 |
API Key 所属专属分组不再允许当前用户使用 | 当前账户无权继续使用该分组。选择其他可用分组或联系支持。 |
ACCESS_DENIED，提示以 Access denied. Your IP is 开头 | 如果密钥设置了 IP 限制，核对当前网络出口 IP 是否被允许；无法确认时联系支持。 |
余额、订阅和密钥各自的限制需要分别检查。单纯充值不会改变密钥过期时间，也不会解除你给密钥设置的额度。
404：地址或模型不匹配
| 错误提示 | 含义 |
|---|---|
Model "…" is not available for this group | 当前分组不允许使用这个模型。 |
Model "…" is not supported by any configured account in this group | 当前分组没有支持这个模型的渠道配置。 |
这里的 … 会显示你实际请求的模型名。
先核对模型名称，再确认密钥当前选择的分组。可以改用该分组支持的模型，或选择支持目标模型的其他可用分组。
如果提示的是地址或页面不存在，而没有具体模型错误，按对应客户端教程重新核对地址。不同客户端对地址是否需要带 /v1 的要求可能不同，不要统一套用同一个写法。
429：先分清额度和繁忙
密钥总额度用完
看到 API key 额度已用完 或 api key 额度已用完，先查看这个密钥设置的额度和已用金额。需要继续使用时，调整该密钥额度或使用另一个合适的密钥。
这是密钥本身的额度限制，充值账户余额后仍可能需要调整密钥设置。
订阅周期额度用完
| 错误提示 | 含义 |
|---|---|
daily usage limit exceeded | 当前日额度已用完。 |
weekly usage limit exceeded | 当前周额度已用完。 |
monthly usage limit exceeded | 当前月额度已用完。 |
到 我的订阅 查看已用额度和重置时间。可以等待对应周期重置，或在有可用余额的前提下选择适合的按量分组；切换前先确认模型和价格。
自己给密钥设置的周期限额
看到以下提示，检查 API 密钥 中该密钥的限额设置及当前用量：
api key 5小时限额已用完api key 日限额已用完api key 7天限额已用完
可以等待对应窗口重置，或根据需要调整你自己的密钥限额。账户仍需有可用余额或有效订阅。
繁忙或上游限流
看到 All available accounts are currently rate-limited. Please retry later.，表示可用渠道暂时处于限流状态。稍等后重试；如果正在同时运行多个任务，先减少并发。
如果看到 Too many pending requests, please retry later 或以 Concurrency limit exceeded for 开头的错误，先减少同时运行的任务，再稍后重试。持续出现时，查看 渠道状态，并把出错时间、模型和分组提供给支持。
这类提示与密钥或订阅额度用完不同，不要仅凭 429 就判断需要充值。
密钥反复验证失败
看到 Too many invalid authentication attempts; retry later，先停止连续重试，修正密钥配置，再稍后重试。
这类提示不表示需要充值。
502 / 503 或连接中断
如果看到 API key authentication is temporarily unavailable 或 Service temporarily unavailable，稍等后再重试。连续出现时，将时间和错误信息提供给支持。
其他 502 / 503 或连接中断，需要结合完整错误判断。先保存错误信息，查看控制台的渠道状态和同一时间的使用记录，再决定是否重试。
已经开始返回内容的请求，也可能在中途失败。不要仅因为出现了一段回复就判断任务已完成；重试前检查客户端是否仍在自动重试或继续运行，避免重复提交较长任务。
400：密钥放进了请求地址
看到 API key in query parameter is deprecated. Please use Authorization header instead.，说明请求把密钥放进了地址参数。
将密钥填写到客户端的 API Key 配置项；开发者应使用请求头传递，不要把真实密钥拼进 URL。密钥的创建和复制方式见 第一次使用。
仍然无法解决
加入 QQ 群 1103052862，说明以下信息，便于定位同一笔请求：
- 出错时间，注明北京时间。
- 客户端名称和版本。
- 使用的模型、分组及密钥名称或编号。
- 完整错误文字或已脱敏截图；如有请求编号，一并提供。
- 你已经尝试过哪些步骤。
分享前隐藏真实 API 密钥、登录密码和私人对话内容。