先记录可比较的证据
每次失败至少记录时间、Profile、模型 ID（不含密钥）、请求类型、状态码或异常类别、耗时和是否重试。不要只记“模型挂了”，也不要把带认证信息的完整请求复制到日志。
一、区分四类问题
- DNS/连接失败：请求可能没有到达供应商；
- TLS/代理失败：检查证书链和代理设置；
- 408/429：请求超时或触发限流；
- 5xx：供应商暂时错误，也可能是网关上游故障；
- 4xx 参数错误：优先检查模型 ID、请求格式和权限，不应盲目重试。
二、用最小请求建立基线
先发送短文本、低复杂度请求，记录成功耗时。再逐步增加上下文、工具和输出长度。若最小请求稳定而复杂任务失败，重点检查上下文预算、工具超时和单次任务设计。
三、采用有限退避
对明确的暂时性错误使用有限次数的指数退避，并加入随机抖动；对认证、权限、模型不存在等确定性错误不要重试。重试次数、总等待时间和最终错误必须可见。
四、注意非幂等副作用
模型请求后可能触发发消息、写文件、创建订单等动作。重试前必须知道上一次是否已经执行成功，否则会产生重复副作用。对外部动作使用唯一操作 ID、结果查询或人工确认。
五、超时分层
区分连接超时、读取超时、工具执行超时和整体任务超时。整体超时太短会误杀正常长任务，太长又会让队列堆积。根据任务类型分别设置，并在日志中报告具体哪一层超时。
如果问题最终定位到 API Key 或 Profile，参考认证排查；如果后台才失败，参考Gateway 进程排查。