HiAPI 402 Error: How to Fix 'Insufficient Balance'

A request to the HiAPI API can fail with an HTTP 402 response and "error_code": "INSUFFICIENT_QUOTA". This means your account's Credits balance has run out — it is not a problem with your API key, your request format, or rate limits. The task is rejected before it is ever created, so nothing is charged. The fix is almost always the same: top up your balance and retry the exact same request.

What the error actually looks like

When your balance can't cover a task, POST /v1/tasks (and the equivalent Playground task-creation calls) respond with HTTP status 402 and a body like this:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

The code field mirrors the HTTP status (402), error_code is the stable machine-readable value to branch your error handling on, and data is always null for a failed task creation. Some general-purpose endpoints (like listing models) use a differently-shaped error envelope for auth problems — see the API key error guide if you're seeing a 401 instead of a 402. The two are not related: 401 means the key itself is invalid or disabled, 402 means the key is fine but the account behind it is out of Credits.

Common causes, most likely first

1. Your balance is genuinely at zero. New accounts start with trial Credits, and once those (plus any top-ups) are spent, every task-creation call returns 402 until you add more Credits.
2. A burst of tasks drained the balance faster than expected. Video models in particular bill per second of output, so running several clips back-to-back can consume a balance much faster than a batch of still images would.
3. You're mistaking a 401 or 429 for a 402. Check the HTTP status code and error_code field directly — a 401 permission_denied (bad or disabled key) and a 429 rate_limited (too many requests) look similar in casual error logs but need different fixes.

Fix it in order

1. Check your current balance. Go to Billing in the dashboard and look at your Credits balance before doing anything else — this confirms whether 402 is really a balance issue.
2. Top up Credits. From the same Billing page, add Credits to your account. There is no separate "unlock" step — once the balance is positive, task creation works immediately.
3. Retry the identical request. No code or payload changes are needed. The same prompt, model, and parameters that failed with 402 will succeed once there's enough balance to cover the task's cost (check Pricing if you're unsure what a given model costs per call).
4. Set up a balance alert for next time. HiAPI has a "Balance Alerts" feature (in the dashboard settings) that sends an email when your balance drops below a threshold you choose, so you can top up before the next task fails.

Minimal verification example

Use this to confirm your account is really the cause, independent of whatever model or SDK you were using when the error first showed up:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a simple test image of a red circle on a white background"
  }'

With an empty balance, this returns:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

After topping up, the same request returns a normal task-created response instead:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

Related

• HiAPI Pricing
• Billing dashboard
• Creating an async task
• API Keys Data Are Invalid: Causes & Fix

FAQ

Why did my balance reach zero without warning? By default you only find out when a task fails with 402. Turning on Balance Alerts in the dashboard sends you an email once your balance drops below a threshold you set, before it hits zero.

Does a 402 error cancel a task that was already running? No. INSUFFICIENT_QUOTA is returned at task-creation time, before any task exists. It can't interrupt something already in progress — it only blocks new tasks from starting.

Will I be charged for a request that fails with 402? No. The balance check happens before the task is created, so a 402 response means no task was created and nothing was deducted from your account.

Is a 402 the same as being rate-limited? No. Rate limiting returns a 429 with error_code: "RATE_LIMITED" and means you're sending requests too fast; 402 means your account balance is insufficient, independent of request frequency.

How do I check my balance before it runs out? Open Billing in the dashboard — your current Credits balance is shown there, along with your transaction history.