统一形状
json
{
"error": {
"type": "invalid_request_error",
"code": "unknown_engine",
"message": "engine 'gpt5' is not a known engine id",
"param": "engine"
},
"request_id": "req_a1b2c3d4"
}
type 与 code 是机器契约；message 可能为清晰度而改写，不要字符串匹配。param 只在错误指向某个参数时出现。错误响应体包含 request_id；同一个值也位于 X-Request-Id 响应头。成功响应体不承诺 request_id，但响应头始终包含 X-Request-Id。
5 个错误类型
text
type typical HTTP status
authentication_error 401
permission_error 403
invalid_request_error 400 / 404
rate_limit_error 429
api_error 500
code 全表
text
code type 含义
missing_api_key authentication_error 缺少 Authorization Bearer 密钥
invalid_api_key authentication_error 密钥未知、已撤销或已过期
insufficient_scope permission_error 密钥缺少端点要求的读 scope
merchant_expired permission_error 商户订阅已过期
rate_limit_exceeded rate_limit_error 每密钥或来源 IP 限流已触发
api_quota_exceeded rate_limit_error 自然月防滥用上限已耗尽
invalid_request invalid_request_error 请求参数或形状无效
invalid_cursor invalid_request_error 游标无法解析或不兼容
invalid_limit invalid_request_error limit 不在 1..1000
invalid_time_range invalid_request_error since/until 无效或顺序错误
unknown_engine invalid_request_error engine 不在 12 引擎目录
invalid_mention invalid_request_error mention 不是有效布尔值
prompt_not_found invalid_request_error 租户内找不到指定 prompt
run_not_found invalid_request_error 租户内找不到指定 run
not_found invalid_request_error 路由或其他资源不存在
internal_error api_error 未预期的服务端错误
重试策略
400、401、403、404 在修改请求或凭证前不要重试。429 等待 Retry-After，并加入随机抖动；5xx 可指数退避重试。所有重试都应设置总时限和最大次数，避免故障期间形成重试风暴。
