限额与错误
本页说明汕拓智算的错误结构、常见状态码与限额,以及如何对失败请求做重试。具体限额取决于你的套餐与控制台配置,本页不给出固定数值。
错误响应结构
错误结构跟随你所用的协议面(由密钥分组的平台决定)。
OpenAI 兼容协议面(/v1/chat/completions、/v1/responses、/v1/images/* 等)返回一个 error 对象:
json
{
"error": {
"type": "...",
"message": "..."
}
}Anthropic 兼容协议面(/v1/messages)返回顶层 type 为 error 的结构:
json
{
"type": "error",
"error": {
"type": "...",
"message": "..."
}
}排查时优先读 error.message,它通常已说明原因;error.type 用于程序化分类。
常见状态码
| 状态码 | 含义 | 怎么办 |
|---|---|---|
| 401 | 缺少或无效的密钥。 | 检查 Authorization: Bearer sk-...(Gemini 原生用 x-goog-api-key)。在控制台确认密钥有效。 |
| 404 | 该端点对你密钥分组的平台不可用。例如在非 OpenAI 分组上调图像生成,或在 OpenAI 分组上调 count_tokens。 | 用与端点匹配平台的密钥,或改用该平台的对应端点。见鉴权。 |
| 429 | 触发限流。 | 退避后重试,见下文。限额取决于套餐,详见控制台。 |
| 5xx | 上游或网关错误。 | 网关可能已自动回退;若仍返回 5xx,退避后重试。回退机制见路由与回退。 |
失败与超时的请求不计费,见计费。
重试与退避
对 429 与 5xx 应重试,且使用指数退避加抖动,避免雪崩式重试。
- 从一个基础间隔开始(如 1 秒),每次重试翻倍,并加入随机抖动。
- 设上限(如最多重试 5 次、单次封顶若干秒),超过则向上抛出错误。
- 若响应带
Retry-After,优先按它指示的时间等待。 401与404是配置类错误,不要重试:先修正密钥或端点。
TIP
5xx 时网关可能已经替你回退到其他可用通道。客户端侧的重试是在此之上的兜底,二者不冲突。
请求体大小限制
请求体有大小上限,由部署方配置(本页不给出固定数值)。超限通常表现为请求被拒。需要更大的请求体时,请在控制台查询或联系运维方确认上限。
限额取决于套餐
速率限制等限额取决于你的套餐与控制台配置,本页不列具体数值。请在控制台查看你当前的限额。