チュートリアル

HiAPI が 402 残高不足（INSUFFICIENT_QUOTA）を返したら？原因と修正手順

Oct 8, 2026

HiAPI の API を呼び出すと、ときどき HTTP 402 レスポンスが返り、レスポンスボディの error_code が INSUFFICIENT_QUOTA になっていることがあります。これはアカウントの Credits 残高がすでに使い切られていることを意味し、API Key が有効かどうか、リクエスト形式が正しいかどうか、レート制限に引っかかったかどうかとは一切関係ありません。タスクは作成前に拒否されるため、課金は一切発生しません。修正方法はほぼ常に同じです。課金ページでアカウントに Credits を追加し、先ほど失敗したリクエストをそのまま再試行してください。

よくある原因

もともと残高が 0 だった。 新規アカウントには登録時のボーナス Credits がありますが、それが尽き、その後のチャージ分も使い切ると、残高が再びプラスになるまでタスク作成系の呼び出しはすべて 402 を返します。
短時間に集中的に呼び出し、残高の消費が想定より速い。 動画系モデルは通常、出力秒数に応じて課金されます。動画クリップを連続して何本か生成すると消費する Credits は、同数の画像タスクをはるかに超えることが多く、気づかないうちに残高が底を突きやすいです。
401 や 429 を 402 と誤認している。 HTTP ステータスコードと error_code フィールドを直接確認してください。401（error_code は permission_denied 系で、Key 自体が無効または無効化されている）と 429（error_code: RATE_LIMITED、リクエストが速すぎる）はどちらも「呼び出し失敗」に見えますが、修正方法は 402 とはまったく異なるため、ログで混ざっていると調査の方向を誤りやすくなります。

修正手順

まず残高を確認する。 コンソールの請求ページを開き、現在の Credits 残高を確認します。この手順で 402 が本当に残高の問題なのかを直接確かめられます。
アカウントにチャージする。 同じく請求ページで Credits を追加します。特別な「解除」手順はなく、残高がプラスになればタスク作成はすぐに成功します。
先ほどのリクエストをそのまま再試行する。 コードやパラメータを変更する必要はありません。同じ prompt、model、その他のフィールドで、残高が十分であればそのまま成功します。特定のモデルの 1 回あたりの呼び出しコストがわからない場合は、先に料金ページを確認してください。
残高アラートを設定し、次回の発生を防ぐ。 コンソールの設定には残高アラート（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 です。

FAQ

残高が突然底を突いたのはなぜですか？それまで何の通知もありませんでした。 デフォルトでは、タスクが実際に 402 で失敗したときに初めて残高不足に気づきます。コンソールの設定で残高アラート（Balance Alerts）をオンにすると、残高が設定したしきい値を下回ったときにメールが届くため、事前にチャージできます。

402 はすでに実行中のタスクを中断しますか？ しません。INSUFFICIENT_QUOTA はタスク作成段階で返されるもので、その時点ではタスクはまだ存在しないため、実行中のタスクを中断するという話にはなりません。新規タスクの作成をブロックするだけです。

402 で失敗したリクエストは課金されますか？ されません。残高チェックはタスクが実際に作成される前に行われるため、402 はタスクが作成されておらず、アカウントから Credits も一切差し引かれていないことを意味します。

402 とレート制限（429）は同じものですか？ いいえ。レート制限は 429 を返し、error_code は RATE_LIMITED で、リクエストの送信が速すぎることを意味します。402 はアカウントの Credits 残高不足を意味し、リクエスト頻度とは無関係で、両者の修正方法も異なります。

残高を使い切る前に事前に知るにはどうすればよいですか？ コンソールの請求ページを開くと、現在の Credits 残高と完全な利用履歴を確認でき、そこで残高アラートのしきい値も設定できます。