错误与重试

应用应记录 HTTP 状态码和网关返回的请求标识，但不要记录完整 API Key 或敏感正文。

状态码	常见原因	建议
400	JSON、参数或模型能力不匹配	修正请求，不自动重试
401	Key 无效、禁用或过期	更换有效 Key
403	分组、模型或 IP 不允许	检查 Key 配置和用户所属分组
404	Base URL 或路径错误	检查是否重复 /v1
429	RPM、TPM、RPD 或上游限流	指数退避并减少并发
500	网关内部异常	保存请求标识并联系管理员
502/503	可用渠道或上游异常	短暂退避后有限次数重试

推荐重试策略

• 仅对 429、502、503 和短暂网络错误自动重试。
• 使用带随机抖动的指数退避，例如 1、2、4、8 秒。
• 设置最大次数和总超时。
• 对图像、音频等可能产生重复任务的请求谨慎重试。
• 敏感分组不会跨组回退；不要在客户端擅自改用不符合数据策略的 Key。