Fix 403 INSUFFICIENT_BALANCE and billing_error

Why BigModel.io returns 403 INSUFFICIENT_BALANCE or billing_error, 402 for video and spend caps, how prepaid USD balance works, and how to keep calling free models.

On this page
  1. What it means
  2. How to fix it
  3. Troubleshooting
  4. Related

Requests stop with this error once your balance cannot pay for them:

json
{ "code": "INSUFFICIENT_BALANCE", "message": "Insufficient balance. Top up at https://bigmodel.io/purchase to continue.", "error": { "message": "Insufficient balance. Top up at https://bigmodel.io/purchase to continue.", "type": "permission_error", "code": "INSUFFICIENT_BALANCE" } }

#What it means

BigModel.io is prepaid: each request is charged from your US-dollar balance at the model's listed price. When the balance is zero or below, paid models return 403. Image, video and audio tasks return 402 insufficient_balance when the balance cannot cover the estimated cost plus your unfinished tasks. Failed requests are never charged.

A 402 spend_cap_reached is different: you reached a weekly or monthly spending cap you set yourself. It has a Retry-After header with the seconds until the cap resets.

#How to fix it

  1. Top up your balance. The balance updates as soon as the payment is confirmed.
  2. Check per-key quotas in API Keys: a key's own USD quota returns 429 API_KEY_QUOTA_EXHAUSTED, not 403.
  3. For spend_cap_reached, wait for the reset or raise the cap on Balance & billing.
  4. With a zero balance you can still call models priced at $0, within a per-minute limit. See Trial credit and free models.

#Troubleshooting

The console shows a balance but requests return 403. The request's estimated cost, which counts max_tokens and your requests still running, is more than what is left. Lower max_tokens, wait for running requests to finish, or top up.

A plan key returns 403 permission_error on a media model. Plan keys cannot use image, video or audio models. Use a pay-as-you-go key.

Updated · View as Markdown