是被封、被限流还是余额不足？先读懂报错再决定动作

调用 LLM API 时突然报错，很多人的第一反应是重试或换 key。但不同错误背后的原因和应对方式完全不同：临时限流重试就能恢复，余额不足需要充值，而永久封禁再重试也是徒劳。错误判断不仅浪费时间和额度，还可能让情况恶化。

先看响应码，再看错误信息

API 返回的错误通常包含 HTTP 状态码和 JSON 格式的错误详情。状态码给出大致分类，错误详情中的 type、code、message 字段提供更具体的线索。

常见状态码与对应的大致方向：

• 401 Unauthorized：认证失败，API key 无效或缺失。
• 403 Forbidden：权限不足，可能涉及封禁或区域限制。
• 429 Too Many Requests：请求频率或并发超限，通常是临时限流。
• 402 Payment Required：余额不足或账单问题。
• 5xx：服务端错误，可能是单模型故障或上游问题。

拿到状态码后，再读 message 和 code。例如同样是 429，有的提示“rate limit exceeded”，有的提示“insufficient quota”，后者其实指向余额问题。

排查决策树

按以下顺序逐层判断，可以快速定位问题。

第一步：检查认证信息

如果返回 401 或明确的“invalid api key”，先确认：

• API key 是否复制完整，有无多余空格。
• key 是否已被删除或禁用。
• 请求头格式是否正确（通常是 Authorization: Bearer <key>）。

这类问题通常不是封禁，修正后即可恢复。

第二步：区分永久封禁与临时限制

403 和部分 429 都可能与限制相关，但性质不同：

• 永久封禁：错误信息通常包含“banned”“suspended”“disabled”等词，且重复请求结果不变。这种情况重试无效，需要联系服务方或更换 key。
• 临时限流：错误信息包含“rate limit”“too many requests”“try again later”，并且短时间后可能恢复。应降低请求频率或等待后重试。

如果服务方提供了 Retry-After 响应头，它直接告诉你建议等待的秒数，优先遵循。

第三步：检查余额与配额

402 或提示“insufficient balance”“quota exceeded”时，说明账户余额不足或配额用尽。此时重试没有意义，需要充值或调整用量。

有些平台将余额不足也返回 429，因此不能只看状态码，必须结合错误信息判断。

第四步：判断是否为单模型故障

如果错误集中在某一个模型上，而其他模型正常，很可能是该模型的上游故障或临时不可用。特征包括：

• 只有特定模型返回 5xx 或超时。
• 切换其他模型后请求成功。
• 错误信息提到“model overloaded”“service unavailable”。

这种情况下，可以临时切换到其他可用模型，或等待一段时间后重试。

重试策略

不同错误需要不同的重试策略：

• 认证错误（401）：不要重试，先修正 key。
• 永久封禁（403）：不要重试，联系服务方或更换 key。
• 余额不足（402 或相关提示）：不要重试，充值或调整用量。
• 临时限流（429）：使用指数退避重试，并遵循 Retry-After。
• 服务端错误（5xx）：可重试，但同样建议指数退避，并设置最大重试次数。

指数退避的基本做法是：第一次等待 1 秒，第二次 2 秒，第三次 4 秒，以此类推，并加入随机抖动，避免多个客户端同时重试造成二次拥堵。

记录与监控

为了更快定位问题，建议在客户端记录每次请求的：

• 时间戳
• 使用的模型
• 状态码和错误信息
• 重试次数

这样当问题再次出现时，你可以快速判断是普遍现象还是个别现象，从而做出正确的响应动作。

小结

遇到报错时，先看状态码和错误信息，再按决策树判断：是认证问题、永久封禁、余额不足、临时限流，还是单模型故障。不同原因对应不同的动作，盲目重试往往无效甚至有害。掌握这套排查方法，能帮你在使用任何 LLM API 时都更从容。