Skip to main content

错误响应格式

Chat Completions、Responses、Messages 和 Gemini 是公开协议边界,不是 Web API。原生协议错误不会包装成 Web 的 { success, data, error } envelope。下面示例只适用于 Chat 和 Responses 的 OpenAI 兼容 gateway 错误:
OpenAI 兼容 gateway 错误会包含 messagetypecodeparam 和提示扩展是可选项。Messages 和 Gemini 使用各自的原生错误格式。可以安全返回的 service validation 错误会原样保留;确定性的 400/422 不重试,交付第一个 byte 后也不重试。

HTTP 状态码

错误类型

认证错误 (401)

支付错误 (402)

访问错误 (403)

验证错误 (400)

公共路由不会在响应体中区分拼写错误、隐藏、延迟或非公开的模型状态。如果模型当前无法通过公共合约访问,AI Sonar 会返回 model_not_found

速率限制错误 (429)

当超过速率限制时:
包含的头部:
Retry-After 头和 retry_after 字段都指示在重试前应等待的确切秒数。

负载过大 (413)

当输入或文件大小超过限制时:
常见原因:
  • 图像文件过大(最大 20MB)
  • 音频文件过大(最大 25MB)
  • 输入文本超过模型上下文长度

服务错误 (5xx)

仅当 retryabletrue 时重试;如果响应包含 retry_after,请等待指定秒数。可根据 alternatives 改用其他可用模型。

在 Python 中处理错误

在 JavaScript 中处理错误

最佳实践

当受到速率限制时,在重试之间逐步延长等待时间:
始终设置合理的超时时间以避免请求挂起:
记录完整的错误响应,包括请求 ID 以便支持:
一些模型有特定要求(例如,最大 tokens、图像格式)。在发起请求前验证输入。