错误响应格式
Chat Completions、Responses、Messages 和 Gemini 是公开协议边界,不是 Web API。原生协议错误不会包装成 Web 的{ success, data, error } envelope。下面示例只适用于 Chat 和 Responses 的 OpenAI 兼容 gateway 错误:
message 和 type;code、param 和提示扩展是可选项。Messages 和 Gemini 使用各自的原生错误格式。可以安全返回的 service validation 错误会原样保留;确定性的 400/422 不重试,交付第一个 byte 后也不重试。
HTTP 状态码
错误类型
认证错误 (401)
支付错误 (402)
访问错误 (403)
验证错误 (400)
model_not_found。
速率限制错误 (429)
当超过速率限制时:Retry-After 头和 retry_after 字段都指示在重试前应等待的确切秒数。
负载过大 (413)
当输入或文件大小超过限制时:- 图像文件过大(最大 20MB)
- 音频文件过大(最大 25MB)
- 输入文本超过模型上下文长度
服务错误 (5xx)
仅当
retryable 为 true 时重试;如果响应包含 retry_after,请等待指定秒数。可根据 alternatives 改用其他可用模型。
在 Python 中处理错误
在 JavaScript 中处理错误
最佳实践
实现指数退避
实现指数退避
当受到速率限制时,在重试之间逐步延长等待时间:
设置超时
设置超时
始终设置合理的超时时间以避免请求挂起:
记录错误以便调试
记录错误以便调试
记录完整的错误响应,包括请求 ID 以便支持:
处理模型特定错误
处理模型特定错误
一些模型有特定要求(例如,最大 tokens、图像格式)。在发起请求前验证输入。