余额预警与欠费

适用角色：组织（顶层用户）、子用户、开发者更新日期：2026-07-02

本文说明余额耗尽和触发限额时系统的行为（含错误码）、低余额预警机制，以及如何快速恢复服务。读懂这一篇，你能分清"是没钱了"还是"被限流了"，并知道各自怎么处理。

一、余额耗尽时会发生什么

新版控制台里，真实扣费始终扣组织余额池。当组织余额耗尽，名下所有 Key 的调用都会被直接拒绝；当某个子用户的额度上限用尽，其名下全部 Key 一并被拒。

按 HTTP 状态码可分为"没钱/额度封顶"（403 类）与"触发限流/限额"（429 类）两大类：

场景	HTTP 状态码	含义
组织余额耗尽	403	组织余额 ≤ 0，名下全部调用被拒，需充值
子用户额度上限用尽	403	该子用户名下全部 Key 一并被拒，需上调其额度
Key 限额耗尽（5h / 1d / 7d 窗口，若已启用）	429	该 Key 在对应时间窗口的额度用完，等窗口重置
组织并发超限	429	瞬时并发超出组织并发上限，降低并发或联系管理员调整并发上限

具体错误代码请以接口实际返回的 code 字段为准，本表先按 HTTP 状态类说明。开发者侧的完整错误处理见开发者指南 · 错误码与排障。

两者表现都是"调用被拒"，但范围和处理方式不同：

情况	影响范围	怎么恢复
组织余额欠费	组织名下所有子用户、所有 Key 都无法调用	给组织充值
某子用户额度用尽	仅该子用户名下的全部 Key 被拒，其他子用户不受影响	组织为该子用户上调额度上限（前提是组织余额仍充足）

子用户名下若有多把 Key，它们共享同一个额度上限（即额度上限的累计消费计数）；额度一旦用尽，该子用户的所有 Key 同时被拒，而不是只拒其中某一把。组织余额与子用户额度的关系见三级账户体系。

为避免余额在不知情时耗尽导致服务突然中断，可配置低余额预警，在余额降到阈值时提前通知。

具体可配字段（阈值类型、是否支持百分比等）以控制台实际设置项为准。建议把财务/运维邮箱加入通知列表，让相关同事同步收到预警。

恢复服务很快，充值/调额成功后立即生效：

Q：余额为 0 时调用报什么错？ A：返回 HTTP 403（余额/额度类），名下调用被拒。充值后下一次请求即可恢复。具体错误代码以接口实际返回为准。

Q：429 和 403 有什么区别？ A：403 是没钱了 / 额度封顶（充值或上调额度解决）；429 是触发了限额/限流（需等限额窗口重置或降低并发）。两者处理方式完全不同。

Q：某个子用户突然全部 Key 都调不通，但其他子用户正常，为什么？ A：很可能是该子用户的额度上限用尽。子用户名下所有 Key 共享同一额度上限，额度用尽时这些 Key 会一并被拒。组织为其上调额度（组织余额需充足）即可恢复。

Q：充值后多久能恢复调用？ A：立即生效。充值/调额成功后，下一次请求即可正常调用。

Q：欠费期间 API Key 会失效吗？ A：不会。Key 本身保留，只是余额/额度不足时调用被拒，恢复后照常可用。