错误码

调用失败时，返回结构兼容 OpenAI 的错误格式：

{
  "error": {
    "message": "错误描述",
    "type": "new_api_error",
    "code": ""
  }
}

HTTP 状态码

状态码	含义	常见原因	处理方式
400	请求参数错误	model 填错、messages 格式不对、参数超范围	对照下方排查，确认 model 用的是模型列表里的 ID
401	鉴权失败	密钥错误、密钥被吊销、请求头格式不对	检查 Authorization: Bearer sk-xxx 格式与密钥有效性
403	无权限	密钥被禁、账号被停用、访问了无权使用的模型或分组	联系平台商务确认账号与模型权限
404	路径或模型不存在	Base URL 写错、模型已下架	确认 Base URL 为 https://cn.guanqiintelligence.com/v1
429	触发限流	请求频率超过速率限制	降低并发或加入重试退避
500	服务端错误	上游异常	稍后重试；持续出现请联系我们
502/503	上游不可用	上游服务波动	稍后重试，我们会自动做故障转移

常见错误与排查

Invalid token / HTTP 401

密钥无效或已被吊销。

# 正确的请求头格式
-H "Authorization: Bearer sk-你的密钥"

# 常见错误：漏了 Bearer、多了引号、密钥前后有空格

The model ... does not exist / HTTP 404

model 字段填错了。注意：

• 必须填完整模型 ID（如 doubao-seed-2-1-turbo-260628），不是显示名称。
• 该模型可能已下架，请查看模型列表确认。

insufficient user quota / 额度不足

账户余额或密钥额度已用尽。请充值或联系平台商务，也可查看计费说明。

用户额度不足

与上一条相同，说明当前余额不足以完成本次请求。

请求成功但内容为空

• 检查 max_tokens 是否设置得过小（例如设成 1）。
• 部分模型会先输出「思考过程」，content 可能为空而 reasoning_content 有内容。

流式输出中断

• 检查客户端超时设置，长回答需要较长等待时间。
• 我们已为流式接口关闭了缓冲，若仍中断请反馈具体 request_id。

提供 request_id 加速排查

每次响应都带 X-Oneapi-Request-Id 或错误信息中含 request id，例如：

Invalid token (request id: 202609120040586049041878268d9d6aUFghynS)

需要我们协助排查时，请提供这个 request_id，我们能据此定位该次调用的完整链路。

重试建议

状态码	是否建议重试
400 / 401 / 403 / 404	❌ 不建议，属确定性问题，重试无用
429	✅ 建议，需指数退避（如 1s、2s、4s…）
500 / 502 / 503	✅ 建议，指数退避后重试

我们已在上游失败时自动重试，因此你收到 5xx 说明重试后仍失败，建议自行再做少量退避重试。