API 错误处理

模型应用的失败不只有“接口报错”。网络可能超时,服务可能限流,HTTP 200 也可能对应拒答、截断或不合业务要求的内容。把所有失败都交给一次自动重试,既不能保证修复,也可能放大费用。

这一节为前面的摘要应用建立处理顺序:先分类,再决定返回、重试、排队还是交给人工。

分清三层失败

层次 例子 优先处理
传输和 HTTP DNS、连接超时、429、5xx 检查网络、服务状态和错误类别
生成状态 拒答、incomplete、流中断、无文本 明确标记未完成,按原因处理
业务验收 摘要失真、分类错误、遗漏信息 改进输入、Prompt 或模型评估

业务错误不能仅靠重发同一请求解决。格式错误也不一定需要换模型,可能是解析器错误地假定了返回位置。

哪些 HTTP 错误值得重试

以下为通用排查建议,实际以提供商错误体中的 code、type 和当前说明为准:

情况 建议
400 等参数错误 修正输入或不支持的参数,不原样重试
401 / 403 检查认证、权限或访问条件,不循环重试
404 检查端点、资源和模型可用性
429 速率限制 减少并发,必要时有界退避
429 额度或账户限制 处理额度与账户问题,等待几秒通常无效
5xx 或临时网络故障 在总时间和次数预算内考虑重试

OpenAI 的错误说明区分了认证、速率和额度等问题;同一 HTTP 状态码不足以决定所有动作。官方错误码

不要把服务方原始异常完整返回浏览器。面向用户解释是否需要修改输入、稍后重试或联系管理员,面向运维保留可追踪的分类与请求标识。

超时不代表上游没有执行

连接建立失败,与已经提交请求但未及时拿到结果不同。读取超时后,上游可能仍在处理,也可能已经生成了答案。

因此,自动重试前应考虑重复生成和计费。对于发送邮件、修改数据等带业务副作用的工具操作,还需要业务幂等保护,不能让语言模型或 HTTP 重试策略决定是否重复执行。

给本地任务分配 ID,可以避免浏览器连点和队列重复消费触发同一业务操作;但本地去重不自动保证上游生成只发生一次。不要假定请求带上任意自定义幂等头,服务就会去重。

把重试限制在可控范围

重试策略至少包含三项:允许重试的错误类别、最大次数,以及整个任务的截止时间。可用指数退避加随机抖动减少同时重试形成的峰值;失败调用也可能消耗限额。速率限制与退避

下面是策略示意,不是直接调用真实服务的实现:

最多 3 次尝试,任务总预算由业务确定
  只有短暂失败才进入重试
  若有适用的 Retry-After,先计算是否还能在截止时间内等待
  否则在指数增长的等待窗口内随机选择延迟
  剩余时间不足以完成一次调用时,停止

不要把三次 90 秒超时简单叠加到一次需要快速返回的网页请求里。等待过长的任务,更适合进入队列并向用户显示处理状态。

SDK、HTTP Client 和任务队列可能各有重试机制。只选择一个主要控制层,并记录真实尝试次数,避免“每层重试三次”变成多倍调用。

流已经开始输出时

如果用户看到一半摘要后连接断开,直接重新调用并接着追加,可能产生重复、矛盾或缺失。除非服务明确支持可靠恢复,否则把这次任务标为未完成;用户重试时启动独立生成,或在明确的产品设计下替换原内容。

流式连接正常结束,但没有完成事件,也按失败处理。HTTP 200 不足以证明整段流成功。

回退也需要验收

模型不可用时,可以返回稍后再试、保存任务排队,或使用预先评估过的备用模型。备用方案仍需满足任务的输入长度、格式和数据要求。

例如摘要功能可以暂时保留原帖,不生成摘要;不能为了“页面一定有内容”,把未经检查的旧摘要套到新帖子上。

留下能解释故障的记录

建议记录任务 ID、尝试次数、错误分类、HTTP 状态、提供商错误码、请求 ID、耗时和最终状态。未知费用保留未知;没有拿到 usage 不代表没有发生调用。

前文控制器只记录异常类型并返回统一错误,是最小教学版本。线上排障时,应按这里的分类增加脱敏字段,而不是直接打开全部请求和响应日志。

本节练习

给摘要应用列出四种情况:无效 Key、短时限流、读取超时、模型返回未完成。分别说明是否重试、最多等待多久,以及界面最终显示什么。

本文章首发在 LearnKu.com 网站上。

上一篇 下一篇
讨论数量: 0
发起讨论 只看当前版本


暂无话题~