Fix 402 Insufficient Balance and Quota Exhausted API Errors

A 402 or an "insufficient balance" message is the one API error with nothing technically wrong: the endpoint is right, the key authenticates, the model exists, and the platform is simply declining to spend money you do not have. It looks like the easiest error on the list, and it still wastes hours, because three different pools of money get conflated under one message, and topping up only refills one of them.

Balance, Quota, and Budget Are Three Different Pools

The confusion is that clients flatten all three into "quota exhausted" or "payment required". If you top up and the error persists, you refilled the wrong pool: the account has money, but the key or budget you are calling through is still capped.

One more distinction worth naming: on official subscription plans, "quota exhausted" often means a plan tier allowance that resets on a schedule and cannot be topped up at all, only upgraded or waited out. On pay-as-you-go platforms, the same words mean a balance or cap you control directly.

Find Out Which Pool Is Empty

Three console checks, in order: the account balance page, the failing key's own limit settings, and, on team accounts, the budget page for your member or model dimension.

Then confirm with a minimal paid request through the failing key, using a cheap model so the test costs a fraction of a cent:

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":"Reply OK"}],"max_tokens":8}'

Read the combination: if this fails on the suspect key but succeeds on a fresh key with no limits, the account has balance and the problem is a per-key cap or budget. If it fails on every key, the account balance itself is empty. Note that a free or cached model-list call proves nothing here; only a request that actually bills tokens tests the money path.

Top Up Without Guesswork

On Zivv, billing is pure pay-as-you-go: you top up at ¥1 = $1, usage draws the balance down per token, and there is no subscription tier to outgrow, with per-token prices at a steep discount to official rates. Two habits make balance management boring, which is the goal:

• Size top-ups from your last 30 days of usage on the usage page, not from guesses
• Treat a fast-draining balance as a per-token cost question: the token cost guide covers estimating spend per model, and current prices live in Model Hub

Add Preflight Checks to Batch Jobs

The expensive version of a 402 is the one that arrives at 3 a.m., at item 4,000 of a 10,000-item overnight batch, after which the job either crashes without a checkpoint or, worse, keeps looping on an error that will never clear. Two pieces of code prevent both.

First, a preflight probe before the batch starts, proving that the exact key, model, and money path work end to end:

def preflight(client, model):
    # One tiny billable request before committing to a long run
    resp = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "Reply OK"}],
        max_tokens=4,
    )
    return resp.choices[0].message.content

def run_batch(client, model, items):
    preflight(client, model)  # raises before item 1, not at item 4000
    for i, item in enumerate(items):
        try:
            process(client, model, item)
        except PaymentRequiredError:
            save_checkpoint(i)          # resume point, work so far is kept
            alert_operator(f"402 at item {i}: balance or cap exhausted")
            raise                        # never retry a 402

Second, that except branch encodes the rule people get wrong: a 402 is not retryable. Backoff exists for transient states, and an empty balance is not transient; it clears only when a human adds money or raises a cap. The correct handling is checkpoint, alert, stop. Pair the probe with a rough cost estimate, item count times average tokens per item times the model's per-token price, and compare it against your balance before launching, not after.

Make Caps Fail Loudly, Not Silently

Per-key limits and budgets are features, not obstacles: a runaway script that hits its own key's cap is a contained incident, while the same script on an uncapped shared key is an emptied account. The structure that works:

• One key per person, project, and automation, each with a limit sized to its job
• On team accounts, budgets per member, per key, and per model, with usage analytics to see drain in real time
• Alerts at 80 percent of a budget, so the conversation happens before the hard stop, not mid-sprint

Shared-balance teams get all of this per member through Teams: the team tops up one balance, every member gets an independent key, and a 402 maps to one visible budget line instead of a whodunit.

FAQ

Should I retry a 402 with backoff? No. It will not clear until the money state changes, and automated retries just generate noise. Checkpoint, alert a human, stop.

Why do I get 402 when the account still shows balance? You are hitting a per-key limit or a budget cap, not the account balance. Check the failing key's settings and, on team accounts, your member and model budgets.

Do requests that fail with 402 cost anything? No. The request is rejected before generation, so no tokens are billed. The damage is lost time and, for unattended jobs, lost progress if you did not checkpoint.

"Quota exhausted" on a subscription versus 402 on pay-as-you-go: what is the difference? A subscription allowance is a plan ceiling that resets on the provider's schedule; you cannot pay your way out mid-window. Pay-as-you-go balance is under your control: top up and continue immediately. Heavy, bursty workloads are usually better served by the latter.

A 402 should be a five-minute fix and a one-line change to your batch runner, not a recurring surprise. Create a Zivv account, top up at ¥1 = $1, set per-key limits that match each job, and let the caps do their quiet work.