API キーデータが無効：このエラーの原因と修正方法

hiapi を呼び出した際に "the api keys data are invalid"（またはアプリが返す類似のバリエーション）というメッセージが表示された場合、リクエストが認証をまったく通過していないことを意味します。その内部では、hiapi 自身の API がこのために特定のエラーを返します：HTTP 401、error.code: "permission_denied"、メッセージは "This API key is invalid. Check that it is correct or use another API key and try again."（この API キーは無効です。正しいか確認するか、別の API キーを使用して再試行してください。）hiapi をラップするあらゆるアプリ——バックエンドプロキシ、OpenAI 互換クライアント、内部 SDK——は同じ 401 を独自の表現で再ラベル付けします。そのため、表示される正確なテキストが hiapi の原文と一致することはほとんどありません。このガイドでは、なぜ発生するのか、そして数分で確認・修正する方法を順を追って説明します。

エラーの実際の見え方

POST https://api.hiapi.ai/v1/tasks（またはその他の hiapi エンドポイント）への失敗したリクエストは次を返します：

{
  "error": {
    "code": "permission_denied",
    "message": "This API key is invalid. Check that it is correct or use another API key and try again. If the issue persists, contact support with request ID: <id>",
    "request_id": "<id>",
    "type": "hiapi_error"
  }
}

HTTP ステータスコードは 401 です。フレームワークや SDK が生のレスポンスを公開しない場合、これを一般的な「API key(s) data are invalid」「unauthorized」「invalid credentials」メッセージに再パッケージする可能性があります——しかし hiapi 側の根本原因は常に同じ 401 です。

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

1. キーの値が誤っている。コピー＆ペーストが途中で切れていた、余分なスペースが入っている、または古いメモからコピーして Dashboard → API Keys の最新キーではなかった場合、この正確なエラーが発生します——キーが文字化けしていても、空でも、そもそも存在しなくても、hiapi が返すメッセージはまったく同じです。
2. プレースホルダーキーが置き換えられていない。チュートリアルやテンプレートからコピーしたコードには sk-your-api-key のようなリテラル文字列が含まれていることがよくあります——これはランダムな文字列とまったく同じ 401 を発生させます。
3. キーがローテーションまたは失効されている。ダッシュボードで新しいキーを作成しても古いキーは自動的に無効になりませんが、手動で失効または再生成すると無効になります——あるデプロイがまだ古い値を参照している場合（再デプロイされていない環境変数、再読み込みされていない .env）、すべてのリクエストが 401 になります。
4. キーが誤ったヘッダーに送信されている。hiapi は Authorization ヘッダーからのみキーを読み取ります。これを x-api-key、api-key、またはクエリパラメータとして送信すると、同じ permission_denied レスポンスが発生します。この場合、hiapi は不正な形式のキーを認識できず——そもそもキーが見えないだけなのです。
5. 実行時環境変数が空である。プロセスが .env ファイルを読み込む前にキー変数を読み取ると、空文字列をキーとして送信します——これも 401 です。
6. キーに隠れた空白や改行が混入している。これは非常に厄介です：シェルスクリプトで echo 経由でシークレットをパイプすると、値の末尾に改行が追加されます。これが Authorization ヘッダーに入ると、別の形でリクエストを破壊します——クリーンな 401 ではなく、文字化けした invalid json body メッセージを伴う 400 になります。破損したヘッダーがリクエストボディに染み出すためです。エラーがクリーンな「invalid key」ではなく不正な形式のリクエストのように見える場合は、まずキーに浮遊する空白や改行がないか確認してください。

順を追って修正する

1. Dashboard → API Keys を開き、キーを再コピーします。古いターミナル履歴やメッセージの値を再利用しないでください——ページから直接コピーしてください。
2. リクエストヘッダーの形式が完全に一致していることを確認します：Authorization: Bearer YOUR_API_KEY。シェルスクリプトでこの値を組み立てる場合は、echo ではなく printf を使用してください——echo は printf が追加しない末尾改行を追加します。
3. リクエストを送信する前に値を出力します（console.log、print、またはデバッグログ）。空でなく、浮遊する引用符、スペース、改行がないことを確認します。
4. 1 回の普通の curl 呼び出し（下記参照）でキーをアプリから切り離してテストします。curl が成功してもアプリが失敗し続ける場合、バグはキー自体ではなくアプリのリクエスト構築方法にあります。
5. 実際に受け取った正確な HTTP ステータスコードを確認します。401 がこのエラーです。402 はアカウント残高が空であることを意味し、キーの誤りではありません。403 はキーは有効だがその特定のモデルの権限が欠けていることを意味します。429 はレート制限を受けていることを意味します。これら 3 つはいずれもキー無効の問題として扱うべきではありません。

最小限の検証例

キー自体に問題があるか確認するには、次のコマンドを直接実行してください（実際のキーに置き換えてください）：

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

有効なキーはすぐにタスク ID を返します：

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

誤ったキーは上記の 401 を返します。curl が taskId レスポンスを返しているのにアプリが依然として「invalid key」エラーをスローする場合、問題はキーではなくアプリのリクエスト構築コードにあります。

関連内容

• Authentication docs —— 完全なリクエストヘッダー形式、キーローテーションガイド、ステータスコードリファレンス。
• Dashboard → API Keys —— キーの作成、コピー、失効を行う場所。
• Rate limits —— 429 と 401 の違いと発生条件。
• Quickstart —— hiapi を初めてセットアップする場合の、初回リクエストの完全なウォークスルー。

よくある質問

「invalid API key」とレート制限は同じものですか？ いいえ。401 permission_denied はキー自体が受け入れられなかったことを意味します。error_code: "RATE_LIMITED" を伴う 429 はキーは問題ないがリクエストが速すぎることを意味します——しきい値についてはレート制限ドキュメントを参照してください。

新しいキーを作成したばかりなのに、まだ無効です——なぜですか？ 新しいキーが実際にリクエストを発行する場所にコピーされていることを確認してください。ダッシュボードの新しいキーは、ハードコードされた古い値、設定されていない環境変数、再デプロイされていない設定ファイルを自動的に修正するわけではありません。

hiapi はリクエストヘッダーにリテラル文字列「Bearer」を要求しますか？ ドキュメントに記載されサポートされている形式は Authorization: Bearer YOUR_API_KEY です——常にこれを使用してください。テストで観察された可能性のある寛容な動作に依存しないでください。ドキュメントに記載されていない動作は予告なく変更される可能性があります。

なぜ curl は動作するのにアプリは動作しないのですか？ 同じキーを使用する curl が成功する場合、キーは有効であり、問題はアプリがリクエストをどのように組み立てるかにあります——通常はコードに Bearer プレフィックスが欠けている、.env の読み込み前に環境変数が読み取られている、またはラッパーライブラリで誤った引数にキーが渡されている、などです。

error.type: "hiapi_error" とはどういう意味ですか？ これは hiapi の汎用エラーエンベロープであり、この認証失敗にも他のリクエストエラーにも使用されます。実際のエラーを理解するには、エンベロープタイプだけでなく error.code（ここでは permission_denied）を確認してください。