错误处理与重试

生产接入不能只处理“成功 / 失败”。应区分鉴权、请求参数、额度、限流、路由和上游故障。

建议分类

类型	常见状态	处理方向
请求问题	400、413	检查请求体、参数、大小和模型能力
鉴权问题	401	检查 Key 与请求头
权限问题	403	检查模型、IP、分组、Key 状态和路由策略
路径问题	404	检查 Base URL、协议和客户端自动拼接
限流 / 额度	429	降低并发，检查额度和上游限流
临时故障	5xx	受控退避并查看日志

重试策略

对 429 和部分临时 5xx，可以使用指数退避和随机抖动，例如：

1s -> 2s -> 4s -> 8s

不要无限重试。

生成请求可能重复计费

对于 POST 生成请求，如果网络在响应返回前中断，客户端有时无法判断上游是否已经接受请求。

因此：

• 不要对所有失败无条件立即重放。
• 设置最大重试次数。
• 对高成本任务优先查看平台日志和任务状态。
• 异步视频等任务应保留 task_id。
• 业务允许时使用自己的请求去重机制。

超时

客户端超时不等于上游一定取消。长推理、图像、音频或视频任务应设置符合业务特点的超时，并区分连接超时、首字节超时和整体处理时间。

日志

至少保存：时间、模型、端点、状态码、客户端请求 ID（如有）和重试次数。不要保存完整 API Key。