错误码与重试

客户端必须先读取 HTTP 状态码，再解析错误体。不要把所有失败都当作可重试的临时错误。

常见状态码

状态码	含义	是否自动重试
400	请求体、参数或模型格式错误	否
401	API Key 缺失、无效或已撤销	否
403	账号、分组或令牌权限不足	否
404	接口、模型或异步任务不存在	否
429	频率、并发或额度限制	是，延迟后有限重试
500	服务内部临时错误	是，有限重试
502	上游服务暂时不可用	是，有限重试
503	服务暂时不可用	是，有限重试

响应体可能包含 error.message、error.type 或服务提供的其他诊断字段。日志应记录请求 ID、状态码和非敏感错误信息，不记录完整鉴权头。

退避策略

仅对 429、500、502 和 503 进行自动重试：

1. 最多发送 3 次，包括首次请求。
2. 使用指数退避，例如约 1、2 秒。
3. 每次延迟加入少量随机抖动，避免多个客户端同时重试。
4. 服务返回 Retry-After 时优先遵循该值。
5. 达到上限后将错误返回给调用方，不进行无限循环。

写操作和异步任务提交可能产生重复任务。只有在接口支持幂等键，或客户端能确认首次提交未被接受时才自动重试。

超时设置

不同接口需要不同的超时：

操作	建议
模型列表、普通对话	根据应用延迟目标设置，一般为几十秒
图片生成	可设置到 300 秒
异步视频提交	只等待任务接收，不等待视频生成完成
异步任务轮询	单次请求使用短超时，总时长由业务限制
图片或视频下载	根据文件大小独立设置下载超时

超时后不要立即高并发重试。对于异步任务，应保存任务 ID 并继续查询同一任务。

JavaScript 判断示例

const retryableStatus = new Set([429, 500, 502, 503])

function shouldRetry(response, attempt) {
  return attempt < 3 && retryableStatus.has(response.status)
}

实际重试实现还应处理网络中断、Retry-After 和随机抖动。

排查顺序

1. 保存状态码、请求 ID 和非敏感错误体。
2. 验证请求 URL、方法、JSON 格式与模型标识。
3. 对 401 检查 API 鉴权。
4. 对 403 或模型错误重新查询 模型列表。
5. 对可重试错误执行有上限的退避策略。