API 报 402 余额不足？余额、配额、预算三件事分清

任务跑一半弹出 402，或者报错里出现 insufficient balance、quota exceeded、budget exceeded，多数人的第一反应是充值。但实践中相当一部分"没钱"报错发生时，账户里明明有钱。原因是"没钱"其实分三种：余额不足、配额用尽、预算超限，三者的归属和解法完全不同，充值只能解决第一种。这篇讲清楚怎么区分三者、各自怎么处理，以及怎么做预检查让长任务不再中途断掉。

三种"没钱"的区别

类型	归属	典型报错	解决动作
余额不足	账户的充值余额	402、`insufficient balance`	充值
配额用尽	平台或上游按时间窗口的用量上限	`quota exceeded`，常伴随 429	等窗口刷新或调整用量结构
预算超限	你或管理员主动设置的消费上限	`budget exceeded`、Key 被暂停	调整预算设置，不需要充值

三者的本质：余额是"账上还有没有钱"，配额是"这个时间段允许你用多少"，预算是"你自己决定最多花多少"。第一个是财务状态，第二个是平台规则，第三个是管理工具。分不清就会出现"充了值还是报错"或"明明有钱却被拒"的困惑。

一个快速自检：如果你从来没主动设置过任何预算，"预算超限"可以先排除（除非你在团队里，管理员替你设了）；如果平台是预充值模式，"余额"就是控制台里那个数字，最容易核实。先排除最容易核实的，剩下的就是答案。

第一步：用三个信号定位类型

信号一：报错关键词。 先用最小请求拿到原始错误正文，不要只看客户端弹窗的转述：

curl https://zivv.pro/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.5-flash","messages":[{"role":"user","content":"ping"}]}'

典型的余额类响应类似下面这样（各平台字段名略有差异，看 message 关键词）：

{
  "error": {
    "message": "insufficient balance to complete this request",
    "type": "insufficient_balance"
  }
}

message 里出现 balance 指向余额，quota 指向配额，budget 或 limit 指向预算。

信号二：控制台数字。 直接登录控制台看余额。余额充足却被拒，基本可以排除余额问题，往配额和预算方向查；余额确实见底，也别急着结束排查——顺手确认一下是不是还有预算同时触顶，避免充值之后二次中断。

信号三：时间规律。 充值后恢复的是余额问题；几分钟或第二天自动恢复的是窗口配额；月初恢复或管理员调整后恢复的是预算周期。

注意有的平台把配额问题放在 429 里返回，错误类型写 insufficient_quota，这类窗口限流的完整排查见 429 限流排查。

余额不足：充值和缓冲线

确认是余额问题后，处理很直接：充值。Zivv 的汇率是 ¥1 = $1，按实际 Token 用量扣费，充多少用多少，没有月费。

比处理更重要的是预防，两个建议：

设置余额缓冲线：按最近 7 天的日均消耗，保持余额至少覆盖 3 到 7 天的用量；跑批任务或 Agent 任务前再人工确认一次
不要等到归零：余额见底时正在跑的长任务会直接中断，损失的不只是这一次请求，还有半途作废的上下文和进度

想估算一个任务大概要花多少钱，可以参考 Token 成本计算指南：按输入输出 Token 估算之后，留出 2 倍缓冲。

还要分清计费模式：订阅制到期是"服务停止"，和余额无关；按量计费没有到期一说，报错要么是余额、要么是规则。Zivv 采用预充值加按量扣费，控制台里的余额就是实时可用额度，核实起来最直接。

配额用尽：和余额无关的"没钱"

配额是平台或上游按时间窗口分配的用量上限，和你账上有多少钱无关。特征：

报错常见 429 或 quota exceeded，而不是 402
等一段时间（几分钟到一个窗口周期）自动恢复
充值不改变任何结果

处理思路是调整用量结构而不是充钱：任务错峰、拆小、把非关键调用分流到轻量模型。如果配额天花板长期低于真实负载，就要换供给结构——Zivv 的账号池调度就是为这种情况准备的，单账号配额被打满时自动切换，调用方无感。

判断配额问题还有一个办法：换一个轻量模型发同样的请求。配额通常按模型或分组计算，如果 claude-opus-4-8 被拒而 gemini-3.5-flash 正常，基本可以确定是特定模型的窗口配额，而不是账户余额。

预算超限：护栏起作用了

预算是主动设置的消费上限，触发时说明护栏正常工作，这不是故障。典型场景在团队：

管理员给每个成员、每个 Key、甚至每个模型维度设了预算
实习生的 Key 每月限额 50 美元，用完即停
自动化任务的 Key 单独限额，防止脚本失控烧钱

成员看到"没钱"报错时，正确路径是找管理员看用量分析，确认是哪个维度触顶，调整预算后立即恢复，全程不需要充值。Zivv 的团队模式支持共享余额下的多维预算：钱在团队账户里统一管理，每个成员、每个 Key、每个模型各有边界，谁用了多少一目了然。

预算也不只是团队功能。个人用户同样建议给自己设一道：比如给实验性项目的 Key 单独限额，失控的脚本最多烧掉限额内的钱。经历过一次"睡前忘了停脚本"的人，都会理解这道护栏的价值。

预检查：让长任务不再中途断掉

402 类错误最伤的不是钱，而是跑了一半的任务。夜间批处理跑到 80% 因为余额归零全部作废，是完全可以避免的事故。三层防护：

任务开始前探活：发一条最小请求，确认余额、Key、模型都正常
成本预估：任务条数乘以单条平均 Token 再乘以单价，确认余额至少是预估的 2 倍
把 402 当作不可重试错误：一旦出现立即暂停并保存进度，重试只会得到同样的结果

对于跑几个小时的任务，还可以在循环里每完成一部分就主动核对一次剩余余额是否仍够覆盖剩余任务量，不够就提前优雅退出——比在进度 80% 时硬碰 402 体面得多。

代码骨架：

import httpx

BASE = "https://zivv.pro/v1"
HEADERS = {"Authorization": "Bearer sk-your-key"}

def preflight_check():
    # 任务开始前的最小探活请求
    resp = httpx.post(
        BASE + "/chat/completions",
        headers=HEADERS,
        json={
            "model": "gemini-3.5-flash",
            "messages": [{"role": "user", "content": "ping"}],
            "max_tokens": 8,
        },
        timeout=30,
    )
    if resp.status_code == 402:
        raise RuntimeError("余额不足，先充值再启动任务")
    resp.raise_for_status()

def run_batch(tasks):
    preflight_check()
    for i, task in enumerate(tasks):
        resp = call_model(task)      # 内部只对 429/5xx 做退避重试
        if resp.status_code == 402:
            save_checkpoint(i)       # 保存进度，续跑时从这里开始
            raise RuntimeError("余额耗尽，已保存进度到第 " + str(i) + " 条")
        save_result(i, resp)

这套骨架的关键是分类处理：429、529 这类临时错误交给重试；402 这类状态错误立即停止并落盘。两类混在一起处理，要么白白重试浪费时间，要么丢掉进度双倍花钱。区分的依据只有一个：这个错误重试之后结果会不会变。会变的交给重试，不会变的立即停下来处理原因。

三个常见误区

误区一：一看到"没钱"就充值。 预算超限和配额用尽充值都解决不了，钱只会躺在账户里。先按第一步定位类型，再决定动作。

误区二：余额告警线设成零。 等到归零才处理，正在跑的任务已经中断了。告警线应该设在"还够跑完当前最大任务"的水位，比如日均消耗的 2 到 3 倍。

误区三：批任务不做断点，中断后从头再跑。 从头再跑意味着已完成部分的费用双倍支出。上面代码骨架里的 save_checkpoint 只有一行，省下的却是真金白银。

常见问题 FAQ

被 402 拒绝的请求扣费吗？ 不扣。请求在计费检查阶段就被拒绝，没有产生模型消耗；已经完成的历史请求正常计费。

充值后多久生效？ 余额到账后新请求即可使用。如果充值后仍然报错，先确认报错类型是不是预算或配额——那两种情况充值解决不了。另外检查客户端有没有缓存旧的错误状态，个别工具会把失败的会话标记住，重开会话即可。

为什么账户有余额，还是提示不足？ 最常见是 Key 或成员级预算触顶，其次是 Key 所在分组的限制。看原始错误正文的关键词，再到控制台核对这个 Key 的预算设置。

配额和预算会同时触发吗？ 会。比如月底预算触顶的同时，高峰期又撞上窗口配额。处理原则不变：先解决报错正文里指向的那一个，恢复后再观察是否还有第二层拦着。

预算设多少合适？ 个人建议按日均消耗的 5 到 10 倍设月预算，留出高强度使用的余量。团队建议给正式成员宽松预算、给实验性任务和自动化脚本严格预算——重点是把"失控烧钱"的可能性隔离在小额度里。

结论

下次看到"没钱"报错，先问三个问题：账上有没有钱（余额）、这个时间窗口的量用完没有（配额）、是不是护栏挡住了（预算）。三个问题对应三种动作：充值、调结构、调设置。长任务加上预检查和断点保存，402 就从事故降级成一条普通日志。团队用户建议直接用共享余额加多维预算的方式管理成本：钱只需要盯一处，成员不用各自充值，管理员看一个总余额加一组预算就够了。注册 Zivv 后在团队模式里几分钟就能配好。