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、短时限流、读取超时、模型返回未完成。分别说明是否重试、最多等待多久,以及界面最终显示什么。
一站式AI产品经理入门指南
关于 LearnKu