流式响应与重试

对话和 Messages 操作可返回 text/event-stream。流式调用不是普通 HTTP 请求的“自动重发版本”，因为服务端 可能已经开始生成、计费或把部分内容交付给用户。

决策顺序

1. 尚未收到任何数据：先判断业务是否允许重复，再对可重试的暂时性失败做有限次数、指数退避重试。
2. 已经收到部分流内容：将结果视为部分交付，不要无条件重放同一请求。
3. 请求超时或连接中断：执行结果可能未知。记录业务请求标识和已交付字节数，由上层工作流决定人工确认、继续或重新创建任务。
4. 认证、模型、余额、套餐或请求格式失败：先修正根因，不应自动重试。

生产接入失败矩阵

失效情形	HTTP / 流状态	用户动作	重复风险
模型不可用	HTTP 404 model_not_found	修正模型选择后重新发起新请求。	未交付内容时无重复风险。
余额或套餐权益不足	HTTP 402 insufficient_balance	补足前置条件后发起新请求，不让客户端跨语境自动改扣。	未交付内容时无重复风险。
上游超时	HTTP 504 upstream_timeout	按未知结果处理，先查询业务自身状态，再决定是否创建新任务。	可能已经生成、计费或触发业务副作用。
部分流中断	text/event-stream 已交付部分内容	不要无条件重放；提示用户结果不完整，并按业务语义确认后续动作。	高，已交付内容可能与重放结果重复。

部分流已经交付时，重复风险为高。

有界重试

建议把重试次数、总等待时间和并发预算作为显式配置。重试前应同时满足：

• 失败属于短暂连接或上游超时，且未交付部分流内容；
• 业务操作可安全重复，或调用方持有可验证的幂等语义；
• 重试不会绕过余额日限额、套餐并发或业务侧成本保护。

超时不是“没有发生”

upstream_timeout 与 upstream_error 表示上游交互没有得到可用结论，不表示模型一定未执行。对于会触发 外部副作用的业务，应该先查询业务自身状态，而不是把相同 prompt 立即重放。

客户端实现建议

• 把网络超时、首字节超时和流空闲超时分别记录。
• 取消请求后向用户展示“结果可能不完整”，不要把已收到内容标为成功完成。
• 对每次重试写入脱敏诊断信息，不记录 API Key、完整 prompt 或完整输出。