#错误处理与重试

稳定的客户端需要区分“修改请求后再试”和“等待后重试”。不要对所有错误无限重试。

#状态码处理

不同兼容协议的错误 JSON 结构可能不同。客户端应先依赖 HTTP 状态码，再记录响应中的 message、type、code 和 Request ID（如果存在），不要只解析一种固定结构。

#推荐重试策略

attempt 1: 约 0.5 秒
attempt 2: 约 1 秒
attempt 3: 约 2 秒
attempt 4: 约 4 秒

每次等待增加随机抖动，并设置总超时与最大尝试次数。GetRouter 不保证所有 429 响应都包含 Retry-After；如果响应提供该 Header，应优先尊重它。

import random
import time

for attempt in range(4):
    try:
        return send_request()
    except RetryableError:
        if attempt == 3:
            raise
        delay = min(8.0, 0.5 * (2 ** attempt))
        time.sleep(delay * random.uniform(0.8, 1.2))

#流式请求

流已经输出部分内容后断开时，重试可能生成不同答案或重复内容。客户端应：

• 标记当前响应不完整；
• 不把两个流直接拼接；
• 由用户或业务逻辑决定是否重新生成；
• 对工具执行和写操作额外做幂等保护。

#异步媒体任务

视频等异步任务创建成功后，应保存任务 ID 并轮询状态。网络超时时，先确认任务是否已创建，再决定是否重新提交，避免产生重复任务和费用。

#记录必要上下文

至少记录：

• 时间与时区；
• HTTP 状态码；
• 脱敏后的 Endpoint；
• 模型 ID；
• API Key 名称或末尾几位；
• Request ID；
• 重试次数和最终结果。

不要记录完整 API Key、完整敏感提示词或用户隐私数据。