错误与重试 - API Docs

先看三项信息

记录 HTTP 状态、错误体中的 message / type / code，以及请求时间、模型 ID 和响应提供的请求标识（如果有）。用这些信息查控制台请求日志。提交排查信息前移除密钥、Cookie 和敏感输入。常见的 OpenAI 兼容错误格式如下；网关、上游和反向代理可能返回不同结构，也可能返回纯文本或 HTML：

{
  "error": {
    "message": "Example error message",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

现象	下一步
400	检查 JSON、必填参数、模型能力及可选参数组合；修改后再试
401 / 403	检查 API Key、账号状态、模型权限和访问限制；不要盲目重试
404 / HTML	核对服务域名、路径前缀、接口和资源 ID
429	区分频率限制、并发限制和配额原因；查看错误及日志，不要无限重试
500 / 502 / 503 / 504	查看网关和上游状态，确认是否已执行，再决定是否重试
连接中断 / 超时	检查网络与各层超时；本地取消不代表服务端没执行
HTTP 200，但没有模型列表	检查 `success: false` 和 `message`；当前模型列表可能用 200 返回内部查询失败
HTTP 200，但生成未完成	检查 Responses `status`、Chat `finish_reason` 以及 SSE 终止事件

实际状态码可能因上游和部署配置而变化。不要仅根据 HTTP 200 判断业务完成。

有边界地重试

SDK 示例关闭了自动重试。生产应用如需重试，应设置次数和总时限上限，使用带随机抖动的指数退避；服务返回 Retry-After 时按其要求等待。权限和参数错误应先修正，额度不足应先处理账号状态。生成请求并非天然幂等。本规范不承诺 Idempotency-Key 支持。超时、断流或 5xx 之后重发，可能产生重复输出或消耗；先查日志和业务状态。流已经输出部分内容时，不要静默重新生成。

模型不可用

先用相同密钥重新查询模型，再确认模型 ID、协议、分组和渠道配置。不要通过随意更换模型掩盖问题；不同模型可能有不同能力和计费。接口支持范围 · 生产接入 · 接入排障 Read in English 模型路由 · 限流与重试 · 请求观测 · AI SDK