错误与故障排查

请求失败时，先用下面的状态码速查表判断问题出在哪一层，再按对应章节逐项处理。绝大多数报错都能在 1 分钟内定位到原因。

状态码速查表

状态码	含义	常见原因与处理
200 OK	请求成功	正常返回数据。
400 Bad Request	请求参数错误	提示词过长、模型名称错误、传参格式有误、缺少必填参数。
401 Unauthorized	密钥认证失败	API Key 输错、存在多余空格、密钥过期重置，或密钥与接口地址不匹配。
402 Payment Required	余额不足	密钥有效，但账户余额不足或免费额度已耗尽，需要充值或更换密钥。
403 Forbidden	访问被禁止	账号风控封禁、IP 被拉黑，或密钥没有对应模型的调用权限。
404 Not Found	接口地址错误	访问路径不存在，也可能是模型名已下线。
429 Too Many Requests	请求频率过高	触发平台限流，需降低并发、增加请求间隔。
500 Internal Server Error	服务商内部故障	非本地配置问题，稍后重试即可。
502 / 503	服务宕机 / 暂时不可用	平台维护，接口暂时无法连通。

一分钟定位

记不住具体原因时，先按口诀判断方向：

• 400 → 请求参数格式出错
• 401 → 钥匙（密钥）错误
• 402 → 额度耗尽、余额不足
• 403 → 权限封禁，禁止访问
• 429 → 调用过快被限流
• 5xx → 服务商服务器故障

按状态码排查

401 密钥认证失败

最常见的报错，按顺序检查：

1. 请求头使用 Authorization: Bearer <你的 API Key>，不要漏掉 Bearer。
2. 仔细检查密钥首尾是否有多余空格或换行，复制粘贴时最容易带进来。
3. 写入环境变量时不要额外添加引号，例如写成 "sk-xxx" 会导致认证失败。
4. 确认 Base URL 与密钥属于同一平台。FluxLane 密钥需配合 https://api.fluxlane.cn 使用，不要混用其他服务商的地址。
5. 密钥是否已被重置或删除。如不确定，请到控制台的 API Keys 页面重新创建并替换。

402 余额不足

说明密钥本身是有效的，问题在账户额度：

1. 到控制台查看账户余额与已用额度。
2. 确认免费额度是否已耗尽。
3. 充值后稍等片刻再重试；如仍报 402，请更换为有效密钥。

403 访问被禁止

1. 确认账户状态是否正常，是否触发风控限制。
2. 确认当前密钥是否被指定了模型范围，且所调用的模型在授权范围内。
3. 如怀疑是 IP 被限制，请联系客服确认。

400 请求参数错误

1. 校验模型名称是否与控制台模型列表完全一致（含大小写与后缀）。
2. 检查提示词是否超出模型的最大上下文长度。
3. 检查请求体 JSON 格式是否正确，是否缺少必填字段（如 model、messages）。

404 接口地址错误

1. 确认 Base URL 中 /v1 只出现一次：https://api.fluxlane.cn/v1。
2. 确认路径没有拼错或出现多余层级。
3. 确认模型名当前仍然可用，已下线的模型也会返回 404。

429 请求频率过高

1. 查看余额与调用日志，先排除额度类原因。
2. 降低客户端并发数，或增大请求间隔。
3. 为请求增加退避重试（如 1s、2s、4s 逐步拉长），不要短间隔高频重试。
4. 若持续出现，请确认当前账户分组和模型额度。

5xx 服务端故障

500、502、503 属于服务商侧问题，与本地配置无关：

1. 先查看控制台公告与渠道状态。
2. 稍后重试，并使用指数退避策略。
3. 如果只有某个模型失败，通常是该模型或渠道状态变化；如果所有请求都失败，再回到账户与密钥排查。

实用注意事项

1. 401、402 类报错不要无限重试，只会无效消耗资源，应先修正配置或补充额度。
2. 粘贴 API 密钥时仔细检查首尾空格；写入环境变量时不要额外加引号。

建议排查顺序

先用状态码判断问题属于哪一类，再按「配置 → 密钥 → 额度 → 权限」的顺序检查，避免盲目改配置。

CC-Switch 配置后仍然失败

1. 确认当前激活的供应商是 FluxLane。
2. 重新检查 Base URL、API Key 和模型名三项是否都正确。
3. 用控制台显示的模型重新测试一次。
4. 回到 FluxLane 用量页面，确认请求是否真的到达。