错误结构
APIPod 媒体和共享服务错误可以使用标准结构:error.code 和 data.error_code,同时始终保留 HTTP 状态码与消息。
HTTP 状态码
常见机器码
提供商和模型错误可能返回其他代码。客户端应把未知代码视为可向前兼容的值,并回退到 HTTP 状态类别处理。
异步失败
任务可能在创建成功后才失败。轮询和 Webhook 会独立于原始创建响应返回任务终态。error_code,向运维人员展示安全消息,并根据语义错误码和任务状态决定是否重试。
重试检查表
- 对
429、503和瞬时5xx使用带随机抖动的指数退避。 - 重试结果不确定的媒体创建请求时,复用原始
Idempotency-Key和未修改的请求体。 - 对
400、401、402、403、404,在导致错误的条件未改变前不要自动重试。 - 为重试次数和总耗时设置上限。
- 记录
X-Request-ID、task_id、HTTP 状态码、机器码和重试次数。