HiAPI 502 / 503 アップストリームエラー：原因と修正方法

POST https://api.hiapi.ai/v1/tasks を呼び出す（または GET /v1/tasks/{id} をポーリングする）と、通常の 200 + taskId ではなく、502 Bad Gateway または 503 Service Unavailable が返ってきます。どちらも 5xx レスポンスであり、問題がサーバー側または転送側にあることを示しています。あなたのリクエストに問題があるわけではありません。誤ったパラメータ、誤ったキー、形式が不正なペイロードを送信したわけではないのです。503 は HiAPI ドキュメントに記載されている「プラットフォームが一時的に利用不可」というシグナルで、再試行すべきことを伝えています。502 はチェーン上のどこかで生成されたゲートウェイレベルのレスポンスです。本ガイドでは、この点を確認する方法、無駄な作業をせずに安全に再試行する方法、そして 502/503 を 504 タイムアウトや TASK_FAILED の結果と区別する方法を説明します。

502 または 503 は実際にどのように見えるか

正常な 200 ではなく、HTTP ステータス行に次のいずれかが表示されます：

• 503 Service Unavailable —— これはドキュメントに記載されています。HiAPI の非同期 API ドキュメントでは 503 を「プラットフォームが一時的に利用不可。しばらくしてから指数バックオフで再試行してください」と記載しており、対応するビジネスコードは TEMPORARILY_UNAVAILABLE（「生成サービスが一時的に利用不可です。しばらくしてから再試行してください。問題が継続する場合はサポートにお問い合わせください。」）です。HiAPI の同期エラーはフラットな JSON エンベロープを使用します——ドキュメントでは 400 の場合が {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"}——したがって、API が返す 503 も同じエンベロープを使用し、error_code: "TEMPORARILY_UNAVAILABLE" を含むはずです。
• 502 Bad Gateway —— これは HiAPI ドキュメントに記載されているステータスコードではありません。標準 HTTP では、502 はゲートウェイまたはプロキシが、アクセスしようとした次のホップから無効または空のレスポンスを受け取ったことを意味します。したがって、あなたが受け取った 502 はチェーン上のゲートウェイ——エッジ/CDN 層、ロードバランサー、またはあなた自身のネットワーク内のプロキシ——によって生成されたものであり、HiAPI アプリケーションが通常の JSON エンベロープを返したものではありません。レスポンスボディは通常、短い HTML またはプレーンテキストのゲートウェイページであり、この非 JSON のレスポンスボディ自体がシグナルです。これは、固定されたドキュメント記載のペイロードを持つアプリケーションエラーではなく、転送/ゲートウェイの状況であることを示しています。

いずれの場合もステータスは 5xx です。問題はサーバー側または転送側にあり、あなたのリクエストにはありません。これは 4xx の逆です——400（パラメータエラー）、401（キーエラー。HiAPI はネストされた {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}} を返します）、または 402（残高不足）——これらはあなた側で何かを変更して修正する必要があります。502/503 はペイロードを変更しても修正できません。

一般的な原因（可能性の高い順）

1. 一時的なプラットフォームの過負荷またはメンテナンスウィンドウ → 503 TEMPORARILY_UNAVAILABLE。これは想定内の、ドキュメントに記載された状況です。自然に回復し、バックオフ再試行で成功します。
2. チェーン上のどこかのゲートウェイまたはプロキシの瞬間的な揺らぎ → 502。エッジ/CDN 層、ロードバランサー、またはあなた自身のネットワーク内のプロキシが一時的にレスポンスの転送に失敗しました。これも一時的なものです。
3. トラフィックの急増が制限を引き起こした。 高負荷時には、代わりに 429 RATE_LIMITED（「しばらくしてから再試行してください。同じリクエストをすぐに再送信することは避けてください」）が表示される場合があります。ステータスが 429 の場合、解決策はより強く再試行することではなく、送信レートを下げることです。
4. 要求されたモデルバックエンドが一時的に利用不可。 HiAPI はタスクレベルでこれを MODEL_UNAVAILABLE（「しばらくしてから再試行するか、モデルを切り替えてください」）として記録します。そのモデルを提供するプラットフォームレベルの一時的な障害も 503 として現れる可能性があります。
5. いいえ、キーエラー、リクエストボディの形式エラー、残高不足ではありません。これらはそれぞれ 401 / 400 / 402 であり、502 や 503 として現れることはありません。

順を追った修正方法

1. 4xx ではなく 5xx であることを確認する。 まずステータスコードを確認します。502/503 はサーバー/転送側に属します。400、401、402、404、409、415、422、429 はあなた側に属します。本当に 502/503 であれば、リクエストボディの書き直しを始めないでください——それは 4xx にのみ有効です。
2. ジッター付きの指数バックオフで再試行する。 ドキュメントは 503 に対して指数バックオフを明確に要求しています。安全なクライアントパターンは、約 1 秒から開始し、試行ごとに倍増（2 秒、4 秒、8 秒……）、上限は約 30〜60 秒とし、多数のクライアントが同期して再試行しないようランダムなジッターを加えます。これらの間隔は推奨されるクライアントパターンであり、HiAPI が公開した時間保証ではありません。
3. 送信を冪等にする。 POST /v1/tasks に Idempotency-Key ヘッダー（任意の UTF-8 文字列、最大 255 バイト）を設定します。502/503 のためにタスクが実際に作成されたか不明な場合、同じキーで再試行するのは安全です。同じキー + 同じリクエストボディは、元の taskId をレスポンスヘッダー Idempotent-Replay: true 付きで返し、2 つ目のタスクを作成したり、2 回目の課金を発生させたりしません。キーはアカウント単位でスコープされ、24 時間後に期限切れになります。完全な規約は Unified Async API ドキュメント を参照してください。
4. キーなしで盲目的に再 POST しない。 Idempotency-Key なしで送信して 502/503 を受け取った場合、あなたが見えないタスクが既に作成されている可能性があります——ポーリングできる taskId がないため、単純な再試行は重複作業と重複課金のリスクがあります。規模を問わず再試行する前にキーを追加してください。
5. ポーリング中に 502/503 が発生した場合は、ポーリングを続けるだけです。 GET /v1/tasks/{id} が返す 5xx はタスク状態を変更しません。終端状態（success / fail）は到達すると固定され、互いに遷移することはないため、バックオフ後に再度ポーリングすれば問題ありません。あるいは callback.url を登録すれば、一時的な 5xx を抜けてポーリングする代わりに、終端状態で通知を受け取れます——配信は少なくとも 1 回であるため、taskId で重複排除してください。
6. タスクレベルの失敗と区別する。 代わりに HTTP 200 + "status": "fail" を受け取った場合、それは 502/503 ではありません——タスクは受け入れられ、実行され、失敗したのです。TASK_FAILED（「1 回再試行してください。問題が継続する場合はサポートにお問い合わせください」）または TASK_TIMEOUT（「そのタスクを再試行してください」）をそれぞれの方法で処理し、盲目的にゲートウェイ再試行を行わないでください。
7. 継続する場合は、猛攻撃するのではなくエスカレーションする。 502/503 が数分間の複数回のバックオフ再試行後も持続する場合、力ずくで解決できる問題ではなく、一時的なプラットフォームイベントとして扱うべきです。積極的な再試行を停止し、エラーボディに request_id が含まれている場合はそれを添えてサポートに連絡してください。HiAPI コンソールからアカウントと接続性が正常か確認できます。

502 / 503 と 504 と TASK_FAILED の比較

これらは混同しやすいですが、どれも「クリーンに返らなかった」ことを意味するものの、異なる対処が必要です：

レスポンス	HTTP ステータスコード	発生元	タスクは課金されるか？	どうすべきか
503 Service Unavailable	503（ドキュメント記載）	HiAPI プラットフォーム——一時的に利用不可または過負荷	レスポンスからは判断不可。タスクが既に存在する可能性あり	バックオフと同じ Idempotency-Key で再試行する
502 Bad Gateway	502（HiAPI ドキュメント外）	チェーン上のゲートウェイ/プロキシ（エッジ、ロードバランサー、またはあなた自身のプロキシ）	レスポンスからは判断不可	バックオフで冪等に再試行する。あなたのネットワークからのみ発生する場合は、あなた側のプロキシを疑う
504 Gateway Timeout	504（HiAPI ドキュメント外）	待機を停止したチェーン上のゲートウェイまたはプロキシ（HiAPI ドキュメントは 504 を記載していない）	レスポンスからは判断不可	502 と同じ。HiAPI は自身のタイムアウトを TASK_TIMEOUT として報告する
TASK_TIMEOUT	200 + "status": "fail"	HiAPI——タスクは実行されたが時間予算を超過	いいえ（予約額は返金済み）	新しいリクエストとしてそのタスクを再試行する
TASK_FAILED	200 + "status": "fail"	HiAPI——タスクは受け入れられ実行されたが、その後失敗	いいえ（予約額は返金済み）	1 回再試行し、その後 error.message を読む
429 RATE_LIMITED	429	HiAPI——送信が速すぎる	タスクなし	バックオフする。すぐに再送信しない
400 / 401 / 402	4xx	HiAPI——クライアント側（リクエストボディ/キー/残高エラー）	いいえ	リクエスト、キー、残高を修正する。再試行しても無駄

一言で判断すると：502/503/504 は HTTP 転送エラーであり、タスク結果を一切伴いません。一方 TASK_FAILED / TASK_TIMEOUT は HTTP 200 + "status": "fail" と error オブジェクトの形式で到達します。前者は「リクエストが届いたかどうかわからない」ことを意味し、後者は「リクエストは届き、タスクは実行され、そして失敗した」ことを意味します。

最小検証例

クリーンな送信でキーと接続性が正常であることを証明し、502/503 を一時的な問題として切り分けます。確実に動作するモデル id（例：gpt-image-2/text-to-image）を使用し、再試行が安全になるよう Idempotency-Key を含めます：

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

送信自体が 200 と taskId を返した場合、認証とネットワークパスは正常であり、以前の 502/503 は一時的なサーバー/転送状況でした——失敗した呼び出しを再試行してください（同じ Idempotency-Key を再利用すると、重複タスクではなく元のタスクが返されます）。送信が代わりに 401 または 400 を返した場合、それはクライアント側の問題であり、502/503 ではありません。

関連記事

• HiAPI タスクタイムアウトと 504 エラー：修正方法 —— 生の 504 が HiAPI から来ない理由と、TASK_TIMEOUT の意味。
• HiAPI TASK_FAILED エラー：原因と修正方法 —— 200 + "status": "fail" を返すタスクの処理。
• hiapi /v1/tasks ジョブがハングまたはタイムアウトする場合：診断と再試行 —— ポーリング間隔と再試行戦略の詳細。
• HiAPI レート制限 (429) エラーの修正方法 —— 本当の問題が可用性ではなく送信レートである場合。
• 失敗した HiAPI リクエストにも課金されるのはなぜ？ —— 失敗タスクの予約と返金の仕組み。

よくある質問

502 や 503 は私のせいですか？ いいえ。どちらも 5xx レスポンスであり、サーバー側または転送側に属します。あなたの API キーとリクエストボディは引き金ではありません——4xx（400/401/402）こそがあなたが引き起こし、修正できる類のものです。502/503 に対する正しい対応は冪等な再試行であり、コードの変更ではありません。

HiAPI で 502 と 503 の違いは何ですか？ 503 は HiAPI ドキュメントに記載された「プラットフォームが一時的に利用不可」コード（error_code: TEMPORARILY_UNAVAILABLE）で、プラットフォーム自体から来ます。502 は HiAPI ドキュメントに記載されたステータスコードではありません。標準 HTTP では、チェーン上のゲートウェイまたはプロキシが上流から無効なレスポンスを受け取ったときに発行されます。どちらも一時的でバックオフ再試行が必要ですが、502 はあなた自身のネットワーク内のプロキシを指す場合もあります。

503 と 504 はどう違いますか？ 503 はサービスが現在一時的に利用不可または過負荷であることを意味します。504 Gateway Timeout はどこかがレスポンスを待ちすぎたことを意味します。HiAPI ドキュメントは 504 を記載していません。それが表示される場合、チェーン上のどこかのゲートウェイまたはプロキシが待機を諦めたことを意味します。HiAPI 自身の「時間がかかりすぎた」状態はタスク結果 TASK_TIMEOUT（HTTP 200 + "status": "fail"）です。上記の 504 ガイドを参照してください。

502/503 と TASK_FAILED の結果をどう区別しますか？ HTTP ステータスコードを見てください。502/503 はタスクペイロードのない HTTP エラーです。TASK_FAILED は HTTP 200 + "status": "fail" と error オブジェクトの形式で返されます——タスクは受け入れられ実行されました。502/503 にはバックオフ再試行を使用し、TASK_FAILED には 1 回再試行してから error.message を読んでください。

502/503 の後に再試行すると、二重課金されたり重複タスクが作成されたりしますか？ POST /v1/tasks に Idempotency-Key ヘッダーを送信すれば、そうはなりません。同じキー + リクエストボディを再利用すると、重複タスクを作成せずに元の taskId（Idempotent-Replay: true）が返されます。また、失敗したタスクには決して課金されません——タスクが失敗の終端状態に到達すると、作成時に予約された金額は全額返金されます。

どのくらいバックオフすべきで、いつエスカレーションすべきですか？ ジッター付きの指数バックオフ（例：1 秒、2 秒、4 秒、8 秒、上限を設定し、ランダム性を加える）を使用してください。502/503 が数分間の複数回の再試行後も返り続ける場合、積極的な再試行を停止し、エラーボディの request_id を添えてサポートに連絡してください——持続的な 5xx は通常、より速い再試行ループで解決できる問題ではなく、一時的なプラットフォームイベントを意味します。

502/503 が表示されたときにリクエストペイロードを変更すべきですか？ いいえ。502/503 は検証エラーではないため、パラメータを変更しても役に立たず、真の一時的な原因を覆い隠す可能性があります。リクエストをそのままにし、まだ追加していなければ Idempotency-Key を追加して、バックオフで再試行してください。