HiAPI 返回 402 余额不足：排查与修复指南

调用 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 余额和完整的消费记录，也可以在那里设置余额提醒阈值。