HiAPI タスクのタイムアウトと 504 エラー：診断と修正ガイド

HiAPI のタスクでは、GET /v1/tasks/{id} が返すレスポンスの中で、ときに "status": "fail"、"error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} が現れることがあります——ここで注意すべきは、このレスポンス自体の HTTP ステータスコードが 200 であることです。これは HiAPI がドキュメント化している実際の失敗状態であり、タスクは実行を開始したものの、内部の時間予算内に完了できなかったことを意味します。もし目にしているのがこの種の JSON ではなく、クライアントが直接投げる素の HTTP 504 Gateway Timeout であれば、それは HiAPI の API が返したものではまったくありません：504 は HiAPI がドキュメント化しているどのステータスコードリストにも含まれていません。本記事ではこの 2 つのケースを分けて解説します。本当の TASK_TIMEOUT をどう読み、どう直すのか。そして 504 が一体どこから現れるのか。

エラーの実際の見え方

HiAPI のタスクフローは非同期です：POST /v1/tasks が即座に taskId を返し、その後 GET /v1/tasks/{id} をポーリングして結果を取得します。error フィールドが現れるのは、status が終態に達したときだけです。本当のタイムアウトは次のようになります：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

このレスポンスの HTTP ステータスコードが 200 であることに注意してください——ポーリングというリクエスト自体は成功しており、失敗しているのはタスクであり、失敗の詳細は data.error の中にあります。これは作成段階の同期的な失敗とは異なります（たとえば残高不足は 402、リクエストボディが不正なら 400）。そうしたエラーは最初の POST /v1/tasks 呼び出しで即座に返され、その時点ではタスクはまだ作成されていません。TASK_TIMEOUT は、作成に成功したタスクにのみ発生します。

一方 504 は、ほとんどの場合レスポンスボディではなく、プロキシ、ロードバランサー、あるいは一部の HTTP クライアントライブラリがレスポンスの待機を諦めたときに自ら吐き出すステータスコードです。HiAPI がドキュメント化している HTTP ステータスコードは 200、400、402、404、409、415、422、503 であり、504 は含まれていません。もし目にしているのが実は 401 であれば、それは別の問題（API Key が無効または無効化されているのであり、タイムアウトではない）であり、本記事の対象外です。

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

1. 実際のタスクレベルのタイムアウト。モデルはタスクを受け取ったものの、内部の時間予算内に完了できませんでした。これが上に示した TASK_TIMEOUT のシナリオであり、より重いタスクでよく発生します——より長い動画の長さ、より高い解像度、あるいはモデル自体の一時的な過負荷などです。
2. 504 は HiAPI の外部から来る。ほとんどの「504」報告は、実はクライアント自身の read timeout（HTTP ライブラリが待ちきれずに諦めた）、あるいはあなたと api.hiapi.ai の間にある社内プロキシ、VPN、ロードバランサーが独自のタイムアウト設定で接続を切断したものです。HiAPI は決して 504 を返さないので、これはクライアントまたはネットワーク側の設定問題であり、HiAPI の障害ではありません。
3. タスクがまだ実行中で、タイムアウトと誤判定されている。queued、handling、archiving はいずれも非終態であり、この時点では error フィールドは存在しません。一度のポーリングでステータスが success でなかったからといって、タイムアウトとは限りません。

修正手順

1. taskId でタスクを取得し、status と error.code を直接読む。 クライアントコードの漠然とした例外メッセージから原因を推測しないでください——GET /v1/tasks/{id} を呼び出し、レスポンスボディそのものを確認します。
2. status が "fail" かつ error.code が "TASK_TIMEOUT" の場合：リトライ。 ドキュメント化された修正方法はこれだけです——新しい POST /v1/tasks 呼び出しで再送信します（新しい taskId を取得）。アカウントや Key を変更する必要はありません。
3. タスク自体が重い場合は、まず入力を確認する。 より長い動画の長さ、より高い解像度、あるいは非常に巨大・複雑なプロンプトは、モデルを時間予算の上限に近づけます。同じ設定で繰り返しタイムアウトする場合は、より低い解像度や短い長さを試すか、別のモデルに切り替えてください。
4. 目にしているのが実は素の 504（error.code を含む JSON レスポンスボディがない）場合、問題は HiAPI の外部にあります。 自身の HTTP クライアントや SDK に設定された read timeout を確認してください——多くのデフォルト値は短め（10〜30 秒）で、非同期フローでは 1 回の長いリクエストでブロックすべきではなく、分けてポーリングすべきです。同時に、社内プロキシ、VPN ゲートウェイ、ロードバランサーを経由していないか確認してください。それらは HiAPI とはまったく無関係に、独自のタイムアウト設定で接続を切断する可能性があります。
5. status が依然として queued、handling、archiving の場合、まだリトライしないでください。 何も実際には失敗していません。より完全な診断については hiapi タスクのスタック・タイムアウト診断ガイド（英語）を参照してください。

最小検証サンプル

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

これにより即座に taskId が返ります：

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

その後、これをポーリングします：

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

正常なタスクは最終的に "status": "success" と出力結果を返します。本当にタイムアウトしたタスクは、先に示した TASK_TIMEOUT 構造を返します。もし得られたのが接続レベルの 504 で、JSON レスポンスボディがまったくない場合、レスポンスが HiAPI の API から返ってこられなかったことを意味します——上記の手順に従って自身のクライアントのタイムアウト設定とネットワーク経路を確認し、アカウントの問題を疑わないでください。

関連内部リンク

• HiAPI コンソール
• 非同期タスクの作成（API ドキュメント）
• hiapi タスクのスタック・タイムアウト診断ガイド（英語）

FAQ

HiAPI の TASK_TIMEOUT と HTTP 504 Gateway Timeout は同じものですか？ いいえ。TASK_TIMEOUT は HiAPI がドキュメント化しているエラーコードで、正常な 200 レスポンスの中に現れ、タスク自身の status が fail になったこと、つまりタスク内部でタイムアウトしたことを表します。504 は一部のプロキシ、ロードバランサー、HTTP クライアントライブラリがレスポンスの待機を諦めたときに返す汎用 HTTP ステータスコードです。HiAPI の API は 504 をドキュメント化も返しもしないので、目にしたリテラルの 504 は必ずあなたと HiAPI の間のどこか、あるいはあなた自身のクライアントが待機を諦めたものであり、HiAPI サーバー側の障害ではありません。

TASK_TIMEOUT に遭遇したらどうすればよいですか？ 新しいタスクを再送信するだけで構いません。TASK_TIMEOUT のドキュメント化された修正方法はリトライであり、別途の解除手順はなく、同じ入力で繰り返しタイムアウトしない限り、プロンプトやパラメータを変更する必要もありません。

タイムアウトしたタスクをリトライすると 2 回課金されますか？ HiAPI のドキュメント化されたエラーコード表にはこの点が明記されていません。これが重要であれば、コンソールでこの具体的な taskId を使って使用量記録を確認し、推測で判断しないでください。

自分の HTTP クライアントがタイムアウト例外を投げました。JSON 形式の TASK_TIMEOUT ではありませんが、同じものですか？ いいえ。クライアント自身のタイムアウト（たとえば HTTP ライブラリの ReadTimeout、あるいは社内プロキシが返す 504）は、HiAPI からの何らかのレスポンスを受け取る前に接続を自ら諦めたことを意味し、タスク自体が失敗したことを表しません。/v1/tasks は非同期なので、一般的な修正方法はクライアントの read timeout を引き上げる（あるいは最初の POST でブロックして待たない）ことと、GET /v1/tasks/{id} を分けてポーリングし終態が現れるまで待つことです。

タスクがすでに queued や handling のまま数分経っています。エラーはありませんが、これはタイムアウトですか？ まだそうではありません。queued、handling、archiving はいずれも非終態であり、error フィールドは status が fail になって初めて現れます。もしタスクが本当に収束しない場合は、hiapi タスクのスタック・タイムアウト診断ガイド（英語）にある、キュー滞留などの進行中の原因についての完全な解説を参照してください。