错误排查

先看 HTTP 状态码和返回体里的 error.code / error.message。所有错误体的结构一致：

{
  "error": {
    "code": "...",
    "message": "...（request id: 2026...）"
  }
}

示例中省略了 type（错误类型标识）字段，判断问题请以 error.code 和 error.message 为准。

message 末尾的 request id 请保留，向管理员反馈问题时附上它，也可以在 使用日志 的「请求 ID」筛选框里直接定位那一次请求。

下表中的错误体均为线上实测返回（request id 已省略）。

401 Invalid token复制锚点链接

{
  "error": {
    "code": "",
    "message": "Invalid token"
  }
}

检查清单：

1. Key 是否完整，以 sk- 开头。
2. 请求头是否是 Authorization: Bearer sk-...（Anthropic 格式用 x-api-key）。
3. 环境变量是否真的生效：echo ${#ATHANDRA_API_KEY} 看长度是否不为 0。
4. 令牌是否在控制台被删除、禁用或已过期。
5. Key 中是否混入了换行、空格等不可见字符；这种情况有时连 JSON 错误体都没有，直接返回一个空 body 的 400，重新复制 Key 即可。

额度不足复制锚点链接

HTTP 403：

{
  "error": {
    "message": "token quota is not enough, token remain quota: ＄0.000002, need quota: ＄0.000146",
    "param": "",
    "code": "pre_consume_token_quota_failed"
  }
}

含义：令牌剩余额度（remain quota）小于本次预估需要的额度（need quota）。处理：

• 在「API 密钥」页给该令牌调高额度，或改为无限额度。
• 若令牌本身没问题，检查账户余额是否也用完，用兑换码充值或联系管理员（见 钱包与额度）。
• 预估额度和 max_tokens、输入长度有关，把 max_tokens 调小可以降低预估值。

模型被令牌限制复制锚点链接

HTTP 403：

{
  "error": {
    "code": "",
    "message": "该令牌无权访问模型 deepseek-v4-flash"
  }
}

这个令牌开启了「模型限制」，且没有包含你请求的模型。编辑令牌，把该模型加入允许列表或关闭模型限制。

模型不存在 / 无可用渠道复制锚点链接

HTTP 503：

{
  "error": {
    "code": "model_not_found",
    "message": "分组 default 下模型 claude-sonnet-4-5 无可用渠道（distributor）"
  }
}

注意这里不是 404。原因有两种，看 message 里的“分组”：

1. 模型名拼错（大小写敏感，例如 MiniMax-M3），或根本没有这个模型。
2. 模型存在，但令牌所在的分组不提供它。例如 default 分组调用原生 Claude 就会这样。

处理：先 GET /v1/models 看当前令牌能用的模型；需要别的模型就用对应分组创建新令牌，见 令牌管理。

请求参数错误复制锚点链接

缺少必填字段时的实测返回：

{
  "error": {
    "message": "field messages is required",
    "param": "",
    "code": "invalid_request"
  }
}

这类错误的 HTTP 状态码可能是 4xx 也可能是 5xx，以 error.code 和 message 为准，不要只看状态码。对照对应接口的必填字段检查：OpenAI 格式要 model 和 messages，Anthropic 格式还要 max_tokens。

上游错误复制锚点链接

请求已经通过平台的鉴权，但上游模型服务返回了错误。这类错误和你的 Key、额度无关，换一个模型通常就能绕过。线上实测遇到过：

上游拒绝访问，HTTP 401（注意这和上面「Invalid token」不同，code 是 "401"，message 来自上游）：

{
  "error": {
    "message": "Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.",
    "code": "401"
  }
}

上游内部错误，HTTP 500：

{
  "error": {
    "message": "System error, please retry later.",
    "code": "bad_response_status_code"
  }
}

模型不支持该接口，例如对 deepseek-v3.2 调用 Responses 接口，HTTP 400：

{
  "error": {
    "message": "<400> ***.***.InvalidParameter: Agent capabilities are not enabled for the current model.",
    "code": "InvalidParameter"
  }
}

处理办法：先确认该模型支持你调用的接口（见 Responses 接口 的实测结论）；5xx 可以稍后重试，持续出现就换模型，并向平台管理员反馈，附上 request id。

429 限流复制锚点链接

429 表示请求频率超过限制，可能来自平台，也可能来自上游模型厂商。目前没有稳定复现手段，所以本文不列出线上实测的错误体，处理办法是通用的：

• 读取响应头里的 Retry-After（如果有），按它等待。
• 使用指数退避重试：等 1 秒、2 秒、4 秒……并加随机抖动，最多重试 3 到 5 次。
• 降低并发，不要一次性发起大量请求。
• OpenAI / Anthropic 官方 SDK 已内置重试，可用 max_retries 调整。

长期稳定被限流，请联系平台管理员调整。

超时复制锚点链接

大模型生成长文本可能需要几十秒甚至更久。非流式请求如果超过中间网络层（CDN、反向代理）的时间上限，会被断开，常见表现是 504 / 524 或客户端读超时。

处理：

1. 优先改用 流式输出：数据持续返回，连接不会因空闲被断开。
2. 调大客户端超时。Python：OpenAI(timeout=120)；Node：new OpenAI({ timeout: 120_000 })。
3. 减少输出长度（调小 max_tokens），或换更快的模型。
4. 推理类模型思考时间长，更适合用流式。

还没解决？复制锚点链接

联系平台管理员时，请提供：时间、请求的模型名、令牌名称（不要发送 Key）、完整错误体里的 request id。