# 常见错误代码与排查 (/docs/support/error-codes)





当 API 调用返回非 `200` 状态码时，返回的 JSON 体中通常会包含详细的 `error.message` 与 `error.type`。以下是常见错误代码的排查指南：

***

## 📋 错误代码速查表 [#-错误代码速查表]

<Accordions>
  <Accordion title="401 Unauthorized (认证失败 / 密钥无效)">
    **可能原因**：

    1. 请求头中未携带 `Authorization: Bearer sk-...`，或 `sk-` 密钥复制不完整、前后含有多余空格。
    2. 该令牌已在控制台中被手动设置为「禁用」状态。
    3. 该令牌已到达设定的「过期时间」。
    4. 当前客户端请求的 IP 不在令牌设置的「IP 白名单」范围内。

    **解决办法**：

    * 前往控制台「令牌」页面检查密钥有效性，或重新生成新令牌。
  </Accordion>

  <Accordion title="429 Too Many Requests (余额不足 / 速率超限)">
    **可能原因**：

    1. **主账户余额用尽**（账户余额不足以支付本次请求预估费用）。
    2. **该令牌的独立额度用尽**（虽然主账户有余额，但该令牌达到了创建时设置的自定义额度上限）。
    3. **短时并发过高**（短时间内发送了超出通道 RPM 承载的请求量）。

    **解决办法**：

    * 检查控制台主余额并充值，或编辑该令牌提升额度上限。
    * 客户端增加指数退避重试（Exponential Backoff）机制。
  </Accordion>

  <Accordion title="400 Bad Request / Context Length Exceeded (参数错误 / 上下文超限)">
    **可能原因**：

    1. 发送的对话上下文、历史消息与提示词总 Token 数超过了当前模型的最大上下文窗口限制。
    2. 请求体 JSON 格式不合法，或参数类型错误（如 `temperature` 传入了字符串）。

    **解决办法**：

    * 裁剪历史上下文对话，或切换至支持超长上下文的模型（如 `GPT-5.6-sol`）。
    * 检查请求参数格式。
  </Accordion>

  <Accordion title="404 Not Found / Model Not Found (模型不存在 / 路径错误)">
    **可能原因**：

    1. 请求的 `model` 参数名称拼写有误（如漏写版本号或大小写不匹配）。
    2. 当前使用的令牌开启了「模型访问白名单」，但白名单中未勾选该模型。
    3. 客户端设置的 Base URL 遗漏了 `/v1` 路径（正确应为 `https://token.astrumflow.com/v1`）。

    **解决办法**：

    * 在控制台「模型广场」中核对标准模型 ID。
    * 检查该令牌的模型白名单设置。
  </Accordion>

  <Accordion title="500 / 502 / 504 Gateway Error (上游波动 / 超时)">
    **可能原因**：

    1. 上游大模型官方服务出现瞬时故障、负载过载或网络抖动。
    2. 生成超长代码或复杂推理时耗时超过了网关超时阈值（如超过 120 秒未返回首包）。

    **解决办法**：

    * 疾旋Token 具备自动化多线路热备容灾，通常 1\~2 次重试即可自动切换至健康通道。
    * 建议在客户端或代码中配置 2\~3 次自动重试。
  </Accordion>
</Accordions>