常见 API 报错与处理

在调用 LLM API 聚合服务时，遇到错误是正常现象。理解错误类型并采取正确的处理策略，可以显著提升应用的健壮性。本文介绍几种常见错误场景及通用处理方法。

鉴权失败

鉴权失败通常表现为请求被拒绝，提示无效的 API key 或权限不足。可能的原因包括：

• API key 输入错误或已失效。
• 请求头中未正确携带 key（如缺少 Authorization 字段）。
• 账户余额不足或已达到使用限制。

处理建议：

1. 检查 API key 是否复制完整，注意前后空格。
2. 确认请求头格式符合文档要求。
3. 登录平台查看账户状态与余额。
4. 若使用环境变量，确保已正确加载。

请求限流（429 类错误）

当请求频率超过服务端限制时，会返回限流错误。聚合站可能对不同模型或整体账户设置速率限制。

处理建议：

• 降低并发请求数，或增加请求间隔。
• 实现指数退避重试：首次等待较短时间，每次重试将等待时间加倍，并加入随机抖动避免惊群。
• 监控限流错误率，动态调整客户端发送速率。

示例退避策略（伪代码）：

延迟 = 基础延迟 * (2 ^ 重试次数) + 随机毫秒

模型不存在或不可用

请求的模型名称拼写错误，或该模型暂时未在聚合站上线，会返回模型不存在的错误。

处理建议：

1. 核对模型名称是否与平台文档一致，注意大小写和版本后缀。
2. 查看平台支持的模型列表，确认所需模型可用。
3. 若模型临时下线，可降级到其他可用模型。

重试与退避最佳实践

并非所有错误都适合重试。通常，网络超时、限流、服务器内部错误可以重试；而鉴权失败、参数错误等则应直接修复。

通用原则：

• 仅对可恢复错误进行重试。
• 设置最大重试次数，避免无限循环。
• 使用指数退避加随机抖动。
• 记录重试日志，便于分析。
• 对于幂等性不明确的请求（如生成内容），重试前需评估副作用。

其他常见问题

• 请求超时：可适当延长客户端超时时间，或检查网络连接。
• 响应格式错误：确认请求体符合 API 规范，如 JSON 格式正确。
• 配额耗尽：检查账户余额或贡献额度，及时充值或调整用量。

遇到错误时，首先阅读响应中的错误信息，结合平台文档排查。保持客户端健壮性，才能更好地利用聚合服务的多模型能力。