跳转到内容

错误码与重试

出错时接口返回非 2xx 状态码,响应体为 JSON:

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

常见错误码

HTTP 状态	常见原因	建议处理
400	参数错误、请求体格式不合法	核对参数与 JSON 格式
401	密钥缺失 / 无效	检查 `Authorization: Bearer sk-...`
403	令牌被禁用、模型分组无权访问	控制台检查令牌状态与分组
404	模型名不存在或未开放	查看模型总览
413	请求体过大(上下文超限)	精简 messages 或换长上下文模型
429	限流或额度不足	退避重试,见限流与 429
500 / 502 / 503	上游模型波动	短暂退避后重试,网关会自动切换可用上游

重试建议

对 429 / 5xx 采用指数退避 + 抖动:如 1s、2s、4s,最多 3–5 次;
400 / 401 / 403 属于确定性错误,重试无意义,应先修复请求;
幂等场景(如图像生成)重复提交前先确认上一次请求的最终状态,避免重复扣费;
生产环境建议记录响应头与 error.message,便于排查是哪个环节返回的错误。