HiAPI レート制限（429）エラーの修正：原因と解決方法

HiAPI ゲートウェイが HTTP 429 Too Many Requests を返す場合、使用中の API Key が https://api.hiapi.ai/v1/tasks（またはポーリングエンドポイント GET /v1/tasks/{taskId}）で許可されているリクエスト頻度や同時実行数の上限を短時間で超えたことを意味します。レスポンスボディは HiAPI 共通のエラーエンベロープ——{"error":{"type":"hiapi_error","code":"...","request_id":"..."}}——に従い、429 ステータスコードを伴います。これを解決するのにサポートへメールを送る必要はほとんどなく、クライアント側に小さな「リトライ + レート制限」ロジックを追加するだけで済みます。本記事では、このエラーとは何か、なぜ発生するのか、そして解消する具体的な手順を説明します。

HiAPI の 429 とはどのようなものか

典型的なリクエストはネットワーク層ではおおよそ次のようになります：

> POST /v1/tasks HTTP/1.1
> Host: api.hiapi.ai
> Authorization: Bearer hi-sk-...
> Content-Type: application/json

< HTTP/1.1 429 Too Many Requests
< Content-Type: application/json
<
{"error":{"type":"hiapi_error","code":"rate_limit_exceeded","request_id":"req_..."}}

ポイントは 2 つあります：

• ステータスコードは 429 であり、401/403 ではありません。 401 は Key が不正または欠落していることを示し、429 は Key に問題はなく、単に送信が速すぎることを示します。両者を混同しないでください。
• レスポンスボディは hiapi_error エンベロープ内の JSON です。 一部の HTTP クライアントはデフォルトでステータスコードしか公開しません。コードがログを残さずにサイレントリトライすると、request_id のような調査手がかりを失ってしまいます。

GPT Image 2、Nano-Banana、flux、Seedance、Wan、HappyHorse といったモデルを呼び出す場合、これらはすべて同じ非同期タスクエンドポイント上で動作するため、同じ Key 単位のレート計算を共有します。

よくある原因（発生確率の高い順）

私たちの経験では、高い順におおよそ次のとおりです：

1. 単一 Key のバーストファンアウト。 一連のプロンプトをループし、それぞれに対して並行して POST /v1/tasks を呼び出し、同時実行数の上限を設けていないケース。十数件の並行タスク作成だけでも、新しいアカウントでは上限に達するのに十分です。
2. GET /v1/tasks/{taskId} への過激なポーリング。 while True: poll(); sleep(0.2) のようなタイトループは、タスク作成と同様にリクエスト量としてカウントされます。サブ秒間隔のポーリングは「タスクを 1 つしか作成していないのに 429 になる」最大の原因です。
3. アカウント単位の同時実行上限。 比較的重いモデル——動画（seedance-2.0、wan2.7-video/*、happyhorse-1.0）や @pro 画像バリアント——はより厳しい同時実行タスク上限に計上されます。こうしたタスクを一度に大量に投入すると、毎分の頻度が高くなくても 429 になります。
4. 1 つの Key を複数環境で共有。 dev、staging、prod がすべて同じ HIAPI_API_KEY を使うと、量が合算されます。各環境を個別に見れば問題なくても、合計すると Key が上限を超えてしまいます。
5. プラン枠の枯渇。 無料枠や残りわずかな有料プランでは、特にプロモーション期間中に、課金エラーではなく 429 として現れることがあります。

具体的なしきい値について：HiAPI の毎分リクエスト数と同時実行上限はお客様のアカウント階層によって異なり、プラットフォームは固定の数値を公表していません。したがって、以下で示す同時実行値（5、3、2）は経験的な出発点であり、公式の制限値ではありません——ダッシュボードの実際の使用量に合わせて調整してください。

修正手順

順番に実行してください。ほとんどのチームはステップ 3 まででアラートに起こされなくなります。

1. ジッター付き指数バックオフを追加する

api.hiapi.ai と通信するすべてのクライアントは、429 に遭遇したら増加する遅延でリトライすべきです——決して即座にリトライしないでください。安全なデフォルト実装：

import random, time, requests

def post_task_with_backoff(body, key, *, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.hiapi.ai/v1/tasks",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=body, timeout=30,
        )
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        retry_after = r.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else delay + random.random()
        time.sleep(min(wait, 30.0))
        delay = min(delay * 2, 30.0)
    raise RuntimeError("rate-limited after retries")

このコードは 2 つの点で正しく動作します：遅延を 30 秒で上限設定すること、そして Retry-After レスポンスヘッダーが存在する場合にそれを優先することです。今回の 429 レスポンスに Retry-After がなくても、「上限設定 + ジッター」の戦略でほとんどのバーストを吸収できます。

2. Key ごとにクライアントの同時実行数を制限する

クライアントにセマフォを追加するのが、単一の変更として最も効果的です。いくつに設定すればよいかわからない場合は、5 から始めてください：

import asyncio, httpx

sem = asyncio.Semaphore(5)

async def create_task(client, body):
    async with sem:
        r = await client.post("https://api.hiapi.ai/v1/tasks", json=body, timeout=30)
        return r.json()

同時に 5 つのタスクを実行するのは、ほとんどのアカウントにとって余裕があります。それでも 429 になる場合は 3 に下げてください。重い動画モデルには通常、別個のより低いセマフォ（2 を試す）が必要です。

3. ポーリングから callback.url に切り替える

本番負荷にとって、GET /v1/tasks/{taskId} のポーリングは良いデフォルトではありません。リクエストボディに callback.url を渡すと、HiAPI はタスクが終態に達したときに結果を POST します：

{
  "model": "Nano-Banana",
  "input": { "prompt": "a calm lake at dawn", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

これにより、O(タスク数 × ポーリング回数) のリクエストパターンが O(タスク数) に圧縮されます——通常は 10〜50 倍の呼び出し量削減となり、ポーリング型 429 のほぼ即効性のある特効薬です。GET /v1/tasks/{taskId} はローカルでのデバッグや低頻度の単発呼び出しに取っておきましょう。

4. ポーリングのペースを落とし、ジッターを加える

コールバックを使えない場合（オフラインスクリプト、ローカル notebook、フォールバックの突合など）は、2〜5 秒より速くポーリングせず、複数のワーカーが一斉に動かないようジッターを加えてください：

import random, time
time.sleep(2 + random.random() * 3)  # 2〜5 秒、ジッター付き

5. 環境ごとに Key を分割する

HiAPI API キーページで、dev、staging、prod の各環境用にそれぞれ Key を生成してください。各環境のバーストが互いに分離され、ある Key が漏洩しても他の環境に影響を与えずに個別に失効できます。

6. 現在の使用量を確認する

HiAPI ダッシュボードを開き、同時実行/プラン上限に達しているのか、それとも一時的なバーストなのかを確認してください。各プランの枠は料金ページで照合できます。使用量がプランよりはるかに少ないのに 429 が続く場合、原因はほぼ間違いなくクライアント側のバーストであり、アカウント自体ではありません。

最小限の検証

リトライ層が準備できたら、Nano-Banana タスクでリンクが通るか確認するのが最も安価な方法です。$HIAPI_API_KEY をあなたの Key に置き換えてください：

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana",
    "input": { "prompt": "a single red apple on a white table", "aspect_ratio": "1:1" }
  }'

成功時はおおよそ次のようになります：{"code":200,"data":{"taskId":"tk-hiapi-..."}}。次に一度ポーリングします：

curl -s -H "Authorization: Bearer $HIAPI_API_KEY" \
  https://api.hiapi.ai/v1/tasks/tk-hiapi-...

ステータスは queued → handling → archiving → success と進み、最終的な data.output[0].url があなたの画像です。この一往復が 200 を返すのにバッチタスクがまだ 429 になる場合、問題はあなたの Key ではなくクライアントの同時実行にあります。

よくある質問

リクエストを 1 つしか送っていないのに、なぜ 429 になるのですか？

ほぼ常に、実際のリクエスト量はタスク作成ではなくポーリングループから来ています。5 つの並行タスクに対して 200ms 間隔でポーリングすると、それだけで毎秒 25 リクエストになります。ポーリングを 2〜5 秒に遅くするか、callback.url に切り替えてください。

HiAPI は必ず Retry-After レスポンスヘッダーを付けますか？

Retry-After は推奨値として扱ってください：あればそれを使い、なければ指数バックオフ（1s、2s、4s……上限 30s）にフォールバックします。いずれにせよ、遅延なしでリトライしないでください——それはバーストをさらに大きくするだけです。

429 と 401 / 403 は同じものですか？

いいえ。401 / 403 は認証失敗を示し、同じ hiapi_error エンベロープを通ります。例えば {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"req_..."}}（実測では 401 の message は “This API key is invalid. Check that it is correct...” を提示します）。401/403 が表示されたら、API キーページで Key の値を確認してください——バックオフでは解決できません。

レート上限を直接上げることはできますか？

トラフィックが実際により高い同時実行上限を必要とする場合は、まず料金ページでプラン枠を確認し、そこからサポートに連絡してください。実際には、上記の修正で上限を一切変更せずに 429 問題の 90% 以上を解決できます。

/v1/tasks の 429 と /v1/tasks/{taskId} の 429 の違いは何ですか？

エンドポイントはそのとき何をしていたかを示すだけです——両者は同じ Key 単位のレート予算を共有しています。作成インターフェースの 429 はファンアウトを示し（同時実行の制限、バッチ処理への変更）、ポーリングインターフェースの 429 はタイトなポーリングループを示します（ペースを落とすかコールバックに切り替える）。完全なリクエスト/レスポンス構造については HiAPI Quickstart と認証ドキュメントをご覧ください。

まとめ

429 はあらゆる本番グレードの API ゲートウェイが返す正常で回復可能なシグナルです。指数バックオフを追加し、クライアントの同時実行数を制限し、ポーリングの代わりにコールバックを使い、ダッシュボードで使用量を確認してください。この 4 つを適切に行えば、429 のことを完全に考えなくてよくなります。本ページは英語原文「How to Fix HiAPI Rate Limit (429) Errors」の簡体字中国語版であり、技術的な詳細は原文と一致しています。