Skip to main content
先使用 HTTP 状态码判断传输层结果,再读取可用的机器可读错误码。人类可读消息适合日志和诊断,不应直接用于程序分支。

错误结构

APIPod 媒体和共享服务错误可以使用标准结构:
认证和协议兼容端点可以使用 OpenAI 兼容结构:
客户端归一化时依次检查 error.codedata.error_code,同时始终保留 HTTP 状态码与消息。

HTTP 状态码

常见机器码

提供商和模型错误可能返回其他代码。客户端应把未知代码视为可向前兼容的值,并回退到 HTTP 状态类别处理。

异步失败

任务可能在创建成功后才失败。轮询和 Webhook 会独立于原始创建响应返回任务终态。
不要把容量或服务错误转换为内容审核错误。保留未知异步 error_code,向运维人员展示安全消息,并根据语义错误码和任务状态决定是否重试。

重试检查表

  • 429503 和瞬时 5xx 使用带随机抖动的指数退避。
  • 重试结果不确定的媒体创建请求时,复用原始 Idempotency-Key 和未修改的请求体。
  • 400401402403404,在导致错误的条件未改变前不要自动重试。
  • 为重试次数和总耗时设置上限。
  • 记录 X-Request-IDtask_id、HTTP 状态码、机器码和重试次数。