常见错误代码与排查
遇到 API 调用报错时的原因分析、排查步骤与解决方案速查。
当 API 调用返回非 200 状态码时，返回的 JSON 体中通常会包含详细的 error.message 与 error.type。以下是常见错误代码的排查指南：
📋 错误代码速查表
可能原因：
- 请求头中未携带
Authorization: Bearer sk-...，或sk-密钥复制不完整、前后含有多余空格。 - 该令牌已在控制台中被手动设置为「禁用」状态。
- 该令牌已到达设定的「过期时间」。
- 当前客户端请求的 IP 不在令牌设置的「IP 白名单」范围内。
解决办法：
- 前往控制台「令牌」页面检查密钥有效性，或重新生成新令牌。
可能原因：
- 主账户余额用尽（账户余额不足以支付本次请求预估费用）。
- 该令牌的独立额度用尽（虽然主账户有余额，但该令牌达到了创建时设置的自定义额度上限）。
- 短时并发过高（短时间内发送了超出通道 RPM 承载的请求量）。
解决办法：
- 检查控制台主余额并充值，或编辑该令牌提升额度上限。
- 客户端增加指数退避重试（Exponential Backoff）机制。
可能原因：
- 发送的对话上下文、历史消息与提示词总 Token 数超过了当前模型的最大上下文窗口限制。
- 请求体 JSON 格式不合法，或参数类型错误（如
temperature传入了字符串）。
解决办法：
- 裁剪历史上下文对话，或切换至支持超长上下文的模型（如
GPT-5.6-sol）。 - 检查请求参数格式。
可能原因：
- 请求的
model参数名称拼写有误（如漏写版本号或大小写不匹配）。 - 当前使用的令牌开启了「模型访问白名单」，但白名单中未勾选该模型。
- 客户端设置的 Base URL 遗漏了
/v1路径（正确应为https://token.astrumflow.com/v1）。
解决办法：
- 在控制台「模型广场」中核对标准模型 ID。
- 检查该令牌的模型白名单设置。
可能原因：
- 上游大模型官方服务出现瞬时故障、负载过载或网络抖动。
- 生成超长代码或复杂推理时耗时超过了网关超时阈值（如超过 120 秒未返回首包）。
解决办法：
- 疾旋Token 具备自动化多线路热备容灾，通常 1~2 次重试即可自动切换至健康通道。
- 建议在客户端或代码中配置 2~3 次自动重试。