AI API错误分类怎么做：别把429、拒答、工具失败和内容拦截混在一起

失败要先分型

很多AI应用只记录一个失败状态，导致排障时所有问题都像模型不稳定。实际上，供应商429、超时、内容过滤、模型拒答、工具参数错误、账单余额不足、业务输入缺字段，处理方式完全不同。混在一起会让告警噪声变大，也会误导优化方向。

至少分六类

第一类是供应商基础设施问题，例如超时、5xx和限流。第二类是账号和计费问题，例如余额、权限和区域限制。第三类是安全策略问题，例如内容过滤或拒答。第四类是工具调用问题，例如参数非法、下游接口失败。第五类是业务输入问题，例如缺少必要数据。第六类是网关策略问题，例如预算、模型白名单或项目配额触发。

错误分类决定自动化动作

供应商限流可以回退或排队；内容过滤不应自动换模型绕过；工具参数错误可以允许有限修复；账单问题要通知管理员；业务输入缺失要让用户补充。把这些错误映射成统一分类，Agent才能做正确的下一步。

中转站能统一供应商差异

不同模型供应商的错误码、字段和语义不完全一致。通过 https://top-api.cc 统一接入时，可以把上游错误规范化成团队内部可理解的分类，再把原始错误保留在审计字段里。这样既方便业务处理，又不丢失排障细节。

检查清单

• 错误是否区分上游、网关、工具和业务输入
• 内容安全拦截是否单独记录
• 429和预算触发是否分开
• 工具失败是否记录工具名、参数校验结果和下游状态
• 自动重试是否只用于可重试错误
• 报表是否能按错误类型统计趋势

结语

AI可靠性不是简单提高成功率，而是知道失败为什么发生。错误分类做清楚，才能让回退、重试、告警和用户提示各走各的路。