跳转到主要内容
每个对话接口都返回与其兼容的 API 标准(OpenAI / Anthropic / Gemini)一致的错误结构。 所有错误响应都带 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 更晚,还需等到该时间。控制重试总时长。 这条规则适用于已确认拒绝与安全的读取请求。媒体提交超时按下方步骤恢复。

模型参数被拒绝

当模型不接受请求中的某个取值时,接口返回 HTTP 400 并附带模型自己的说明。思考相关设置返回错误码 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 错误处理与工具参考。