X-Request-Id 响应头,只返回你排查请求所需的信息。
OpenAI — /v1/chat/completions(以及图片/视频接口)
Anthropic — /v1/messages
Gemini — /v1beta/models/{model}:generateContent
状态码映射
错误的type / status 由 HTTP 状态码推导:
排查鉴权、积分与限流错误
确认收到 HTTP
429 拒绝时,限制重试次数并采用带随机抖动的指数退避。
例如每次在 0 和 min(30_000, 1_000 * 2 ** attempt) 毫秒之间随机等待。
如果响应的 X-RateLimit-Reset 更晚,还需等到该时间。控制重试总时长。
这条规则适用于已确认拒绝与安全的读取请求。媒体提交超时按下方步骤恢复。
模型参数被拒绝
当模型不接受请求中的某个取值时,接口返回 HTTP400 并附带模型自己的说明。思考相关设置返回错误码 invalid_reasoning_effort,消息中会列出该模型接受的取值,便于直接改正而不必反复试错。每个模型支持的思考档位、默认档位以及能否关闭思考,都记录在 GET /v1/models 的 capability_metadata.reasoning 中。
504 表示请求超出时间预算。502 表示模型执行未取得可用响应。先查看结构化错误,再决定是否调整参数。
媒体生成错误与重试
图片和视频生成应依据结构化的error.code 和任务的 status(客户端中的
task.status)决定提示内容和是否重试。
只有明确的内容策略错误码或明确的内容策略拒绝,才应建议修改内容。不能仅凭错误消息提到
safety,或 HTTP 502,推断内容违规。异步任务仍为 pending 或 processing 时,
继续使用同一个 task_id 查询 /v1/tasks/{task_id},不要重复提交生成请求。
- 已知
task_id时,客户端超时后按任务状态说明继续查询原任务。结束后查看credits.charged和计费规则,再决定是否重新提交。 - 提交超时且未收到
task_id时,先检查任务历史。保留收到的request_id或X-Request-Id供支持人员定位。部分视频工具支持文档列出的请求关联方式。 - 将回调视为通知。执行不可逆的业务动作前,先通过带鉴权的任务查询核对任务 ID 和最终结果。参阅 Webhook 回调。
个人 MCP
个人 MCP 工具错误通过isError 与 structuredContent 返回;写入结果不确定时应先检查已有执行。参阅个人 MCP 错误处理与工具参考。