Что делать, если HiAPI возвращает 402 «Недостаточно средств» (INSUFFICIENT_QUOTA)? Причины и шаги исправления

При вызове API HiAPI иногда возвращается HTTP-ответ 402, а в теле ответа error_code равен INSUFFICIENT_QUOTA. Это означает, что баланс Credits на аккаунте исчерпан, и это не связано с тем, действителен ли API Key, правильный ли формат запроса и не сработал ли лимит запросов. Задача отклоняется до создания, поэтому никаких списаний не происходит. Способ исправления почти всегда один и тот же: пополнить Credits на странице оплаты и затем повторить тот же самый неудавшийся запрос без изменений.

Распространённые причины

1. Баланс изначально равен 0. Новые аккаунты получают приветственные Credits, и после того, как они и последующие пополнения израсходованы, любой вызов создания задачи будет возвращать 402, пока баланс снова не станет положительным.
2. Интенсивные вызовы за короткое время, баланс расходуется быстрее, чем ожидалось. Видеомодели обычно тарифицируются по секундам вывода, и несколько последовательных запусков видеоклипов расходуют Credits, как правило, гораздо больше, чем такое же количество задач с изображениями, поэтому баланс может незаметно подойти к нулю.
3. Ошибка 401 или 429 принимается за 402. Смотрите непосредственно HTTP-код статуса и поле error_code: 401 (error_code вроде permission_denied, сам Key недействителен или отключён) и 429 (error_code: RATE_LIMITED, запросы слишком быстрые) выглядят как «сбой вызова», но способы исправления совершенно отличаются от 402, и при смешивании в логах легко пойти не в том направлении при диагностике.

Шаги исправления

1. Сначала проверьте баланс. Откройте страницу биллинга в консоли и посмотрите текущий баланс Credits — этот шаг сразу подтвердит, действительно ли 402 вызван проблемой с балансом.
2. Пополните аккаунт. Там же на странице биллинга добавьте Credits; никаких дополнительных шагов «разблокировки» нет, после того как баланс станет положительным, создание задач сразу же заработает.
3. Повторите предыдущий запрос без изменений. Не нужно менять код или параметры. Тот же prompt, model и другие поля при достаточном балансе сразу сработают; если вы не уверены, сколько примерно стоит один вызов определённой модели, сначала загляните на страницу тарифов.
4. Настройте оповещения о балансе, чтобы не столкнуться с этим снова. В настройках консоли есть функция оповещений о балансе (Balance Alerts): когда баланс опускается ниже заданного вами порога, приходит уведомление по электронной почте, так что можно пополнить счёт до того, как он действительно опустеет.

Минимальный пример проверки

С помощью следующего минимального запроса можно самостоятельно убедиться, что проблема в балансе аккаунта, исключив влияние модели или самого SDK:

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"
  }'

При нулевом балансе возвращается следующая структура:

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

После пополнения при повторении того же запроса вернётся нормальный ответ создания задачи:

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

Обратите внимание: поле code совпадает с HTTP-кодом статуса, error_code — это стабильное значение для ветвления логики, а data при неудачном создании всегда равно null.

Связанные внутренние ссылки

• Тарифы HiAPI
• Биллинг и управление балансом
• Создание асинхронной задачи (документация API)

FAQ

Почему баланс вдруг опустел, ведь раньше не было никаких предупреждений? По умолчанию вы узнаёте о недостатке средств только тогда, когда задача действительно завершается с ошибкой 402. Включите в настройках консоли оповещения о балансе (Balance Alerts), и когда баланс опустится ниже заданного порога, вы получите письмо и сможете пополнить счёт заранее.

Может ли 402 прервать уже выполняющуюся задачу? Нет. INSUFFICIENT_QUOTA возвращается на этапе создания задачи, когда задачи ещё не существует, поэтому речи о прерывании выполняющейся задачи нет — это блокирует только создание новых задач.

Списываются ли средства за запросы, завершившиеся с ошибкой 402? Нет. Проверка баланса происходит до фактического создания задачи; 402 означает, что задача не создана и никакие Credits со счёта не списаны.

402 и ограничение частоты (429) — это одно и то же? Нет. Ограничение частоты возвращает 429 с error_code RATE_LIMITED, что означает слишком быструю отправку запросов; 402 означает недостаточный баланс Credits на аккаунте и не связан с частотой запросов, способы исправления у них тоже разные.

Как узнать заранее, до исчерпания баланса? Откройте страницу биллинга в консоли — там виден текущий баланс Credits и полная история расходов, а также можно задать порог оповещения о балансе.