チュートリアル

HiAPI が 403 モデル権限なしを返す：調査と修正ガイド

403 と 401 を区別し、3 ステップでどの Key に権限がないのかを特定する

Oct 8, 2026

HiAPI の /v1/tasks エンドポイントを呼び出した際に HTTP 403 を受け取った場合、レスポンスボディは通常次のような構造になります：{"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}。これは、API Key 自体は有効で認証はすでに通過しているものの、この Key にはリクエストしたモデルやエンドポイントを呼び出す権限が付与されていないことを示します。これは「Key が無効または欠落」の 401 とは異なる種類の問題です。401 は身元が特定できていない状態、403 は特定できたがこの Key では現在のリソースを利用できない状態です。ほとんどの 403 の修正は非常にシンプルです：Key とモデルの対応関係を確認し、権限のある Key に替えて再試行するだけです。

よくある原因

API Key に現在リクエストしているモデルの使用権限がない——公式ドキュメントにおける 403 の定義はまさに「API キーにこの権限がない」であり、これが最もよくある発生シナリオです。通常、同じ Key で権限範囲外のモデルを呼び出したときに発生します。
Key を間違えている——たとえば本来はメインの Key を使うべきところで、別アカウントや別プロジェクトの権限範囲がより小さい Key を誤って使用してしまう場合です。コピー＆ペースト時に余分なスペースが混入したり、途中で切れたりすることもあります。
「キーが無効」（401）と「キーに権限がない」（403）を混同している——どちらのエラーメッセージにも「権限」に関連する文言が含まれることがあり、同じ考え方で調査すると方向を誤ります。具体的な区別方法は後述します。

修正手順

まず返ってきたのが本当に 403 であり、401 ではないことを確認する——HTTP ステータスコード自体を見てください。エラーメッセージの文言だけを見てはいけません。なぜなら permission_denied というエラーコードは 401 と 403 の両方で出現する可能性があり、区別のポイントは文言ではなくステータスコードだからです。
API キー管理でこの Key の帰属を確認する——リクエストで実際に使用されている Key が確かに想定していたものであり、テストアカウント、旧プロジェクト、他人のアカウントの Key ではないことを確認してください。
現在のモデルがこの Key で利用可能な範囲に含まれているかを確認する——認証ドキュメントと HiAPI の料金を参照して、モデル自体が確かに存在し、かつあなたの呼び出し可能範囲内であることを確認できます。もしモデル ID 自体が誤字であったり提供終了になっている場合、エラーは permission_denied ではなく別のエラーコードになるはずであり、この点で問題の種類を切り分けることができます。
権限があることを確認済みの Key に替え、それ以外のパラメータはまったく同じにして一度再試行する——問題が Key の切り替えで解消するかどうかを検証します。
確認した結果 Key とモデルのどちらにも問題がなく、それでも 403 が安定して再現する場合——レスポンスボディの request_id を記録してサポートに連絡してください。原因を確認しないまま同じリクエストを繰り返し再試行しないでください。

最小検証サンプル

以下では、403 を引き起こすリクエストと修正後の再試行を用いて、2 つの状態における実際のレスポンス構造を示します（MODEL_ID は実際に呼び出している、権限がないと疑われるモデルに置き換えてください）：

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "a simple test prompt"
  }'

権限がない場合のレスポンス：

{
  "error": {
    "code": "permission_denied",
    "message": "当前 API Key 暂不能使用该模型，请检查权限或更换 Key。",
    "request_id": "req_xxxxxxxx",
    "type": "hiapi_error"
  }
}

権限のある Key に替え、それ以外のパラメータは変更せずに再試行：

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

2 つのレスポンスボディの構造が異なることに気づくでしょう。403 のような認証・権限レベルのエラーは一貫して error でオブジェクトを包む形になります。一方、Key が権限チェックを通過し、実際に具体的なビジネスルールの判定に入った後に発生するエラー（たとえば残高不足の 402 など）は、code / data / message というフラットな構造で返されます。どちらの構造かを見れば、問題が認証・権限レイヤーにあるのか、具体的なビジネスルールレイヤーにあるのかを大まかに判断できます。

FAQ

403 と 401 は具体的に何が違うのですか？ 401 はこの Key 自体が無効である、またはリクエストに Key がまったく含まれていないことを示します。つまり身元認証の段階で通過していません。403 は身元認証は通過した（Key 自体は有効）ものの、この Key にはリクエストしたモデルやリソースの使用権限が付与されていないことを示します。両者のレスポンスボディの構造は同じ（どちらも error.code でオブジェクトを包む形）であり、区別の鍵はエラーメッセージ内の文言ではなく HTTP ステータスコード自体です。

Key を替えてもまだ 403 の場合、アカウントの問題ですか？ まず、新しい Key が確かに同じ権限のあるアカウントまたはプロジェクトに属していること、コピー＆ペースト時に余分なスペース、改行、欠落がないことを確認してください。確認しても問題がなく再現する場合は、レスポンスボディの request_id を添えてサポートに連絡してください。

403 は残高不足が原因ですか？ いいえ。残高不足は別のエラーコード（INSUFFICIENT_QUOTA、HTTP 402）に対応しており、権限とは別物です。403 はあくまで「この Key にこのモデルを呼び出す資格があるかどうか」を示すものであり、アカウントの残高の多少とは無関係です。

エラーメッセージに「権限」という文字があれば必ず 403 ですか？ いいえ、必ずしもそうではありません。permission_denied というエラーコードは 401 と 403 の両方で出現する可能性があるため、文言のキーワードだけで判断せず、必ず HTTP ステータスコード自体を直接確認してください。