模型 API 调用错误如何分类，哪些应重试、退避或直接失败？

核心回答

模型 API 错误可以按传输、服务可用性、配额、请求契约、身份权限和生成结果分类。瞬时网络失败、部分 5xx 或过载可以在预算内退避重试；短期限流遵守服务端等待信息；额度耗尽、参数不合法、无权限等需要改变条件，不能原样重发。

收到 HTTP 200 后仍要检查流式错误、终止原因、拒答和输出校验。传输成功与业务成功不是一回事；涉及工具写入时，执行结果未知还要单独处理。

展开解析

1. 用错误类型与上下文共同分类

类别	常见表现	处理方式
连接或传输失败	连接重置、连接超时、读超时	判断瞬时性和可重放性；可恢复时退避，持续故障检查网络与依赖
服务端异常或过载	部分 5xx、供应商过载错误	有界退避，必要时熔断或切合格备用路径
短期速率限制	429，并发、请求或 Token 速率超限	检查限流范围、响应头和剩余预算，等待、排队或降级
长期额度或计费限制	余额不足、组织支出上限等	恢复额度或调整已授权配置，停止即时重复调用
请求契约不满足	错误参数、上下文超限、不支持的模型能力	修正适配、裁剪输入或更换合适模型，再创建新尝试
身份与权限失败	常见 401、403	核对凭证、项目、资源权限；不能盲重试或绕过权限
生成与内容问题	拒答、输出截断、结构化结果不合法	按业务处理拒答、补输出预算或受控纠错，不统一归为网络错误

状态码只是线索。不同供应商的额度错误、资源不存在与过载语义不同；接入时应把它们映射到内部错误分类，并保留原始错误码与请求标识，不能靠异常字符串包含某个词来决定全部行为。

2. 退避策略要限制额外负载

可重试错误也不等于立即重试。使用带上限的指数退避和随机抖动，遵守服务端等待提示，并受任务总时间、费用和尝试预算约束。调用方取消后应停止后续尝试。核对 SDK 的默认重试行为，避免多层策略相乘。

“修复请求后再调用”与“同一请求的传输重试”要分开记录。例如输入超过上下文窗口，删掉无关历史后重发属于输入修正；如果压缩后丢掉业务条件，还必须重新验证回答质量。

3. 流式成功需要终态检查

流式连接建立后可能先收到 200，随后出现错误事件、连接中断或异常结束。因此需要保存首个有效输出时间、最后事件、终止原因和完整性状态。半截 JSON 不能直接提交到下游；已展示的半段答复也不能悄悄拼上另一轮不同模型的输出。

拒答是模型或策略层的结果，未必是服务故障；不要通过反复改写同一请求来绕过拒答。格式失败可向模型提供经过脱敏的校验差异，要求修正，并在通过确定性校验后使用。

4. 写操作超时另设结果未知状态

如果一次调用链已经触发退款等外部动作，客户端超时不能证明它没成功。保留逻辑动作标识与幂等键，通过回执查询或对账判断结果；确认可安全重放后再恢复。不能仅因为外层模型调用报错就重跑整条业务链。

追问

能否把所有 4xx 都设为永不重试？

不能只按大类判断。短期限流常见于 429，有些资源暂时不可见还与一致性有关；但参数、鉴权和永久权限错误原样重试通常无效。最终以供应商契约和业务条件为准。

为什么要保留供应商请求 ID？

应用的 trace_id 关联内部链路，供应商请求 ID 用于核对具体外部尝试和支持排查。多次尝试要分别保存，不应只留最后一次成功记录。

对应教程

参考资料