Données de clé API invalides : causes de cette erreur et comment la corriger

Lorsque vous appelez hiapi et que vous voyez un message du type « the api keys data are invalid » (ou une variante similaire produite par votre application), cela signifie que la requête n'a pas du tout passé l'authentification. En interne, l'API de hiapi renvoie pour cela une erreur spécifique : HTTP 401, error.code: "permission_denied", avec le message « This API key is invalid. Check that it is correct or use another API key and try again. » (Cette clé API est invalide. Vérifiez qu'elle est correcte ou utilisez une autre clé API et réessayez.) Toute application qui encapsule hiapi — proxy backend, client compatible OpenAI, SDK interne — réétiquette ce même 401 avec ses propres termes, c'est pourquoi le texte exact que vous voyez correspond rarement au texte original de hiapi. Ce guide explique étape par étape pourquoi cela se produit et comment le confirmer et le corriger en quelques minutes.

À quoi ressemble réellement l'erreur

Une requête échouée vers POST https://api.hiapi.ai/v1/tasks (ou tout autre point de terminaison hiapi) renvoie :

{
  "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"
  }
}

Le code de statut HTTP est 401. Si votre framework ou SDK n'expose pas la réponse brute, il peut la remballer dans un message générique du type « API key(s) data are invalid », « unauthorized » ou « invalid credentials » — mais la cause profonde côté hiapi reste toujours le même 401.

Causes courantes (classées de la plus probable à la moins probable)

1. La valeur de la clé est erronée. Un copier-coller tronqué, un espace en trop, ou une copie depuis d'anciennes notes au lieu de la clé active dans Dashboard → API Keys déclenchent exactement cette erreur — que la clé soit illisible, vide ou inexistante, hiapi renvoie le même message.
2. La clé de remplacement (placeholder) n'a jamais été remplacée. Le code copié depuis un tutoriel ou un modèle contient souvent une chaîne littérale comme sk-your-api-key — elle produit un 401 exactement comme une chaîne aléatoire.
3. La clé a été renouvelée ou révoquée. Créer une nouvelle clé dans le tableau de bord n'invalide pas automatiquement l'ancienne, mais une révocation manuelle ou une régénération le fait — si un déploiement référence encore l'ancienne valeur (variable d'environnement non redéployée, .env non rechargé), chaque requête renvoie un 401.
4. La clé est envoyée dans le mauvais en-tête. hiapi lit la clé uniquement depuis l'en-tête Authorization. L'envoyer comme x-api-key, api-key ou en tant que paramètre de requête produit la même réponse permission_denied, car dans ce cas hiapi ne voit pas la clé mal formée — il ne voit tout simplement aucune clé.
5. La variable d'environnement est vide au moment de l'exécution. Si votre processus lit la variable de la clé avant de charger le fichier .env, il envoie une chaîne vide comme clé — encore un 401.
6. Des espaces ou sauts de ligne invisibles se sont glissés dans la clé. C'est sournois : transmettre un secret via un pipe echo dans un script shell ajoute un saut de ligne à la fin de la valeur. S'il se retrouve dans l'en-tête Authorization, il casse la requête d'une autre manière — non pas un 401 propre, mais un 400 avec un message illisible invalid json body, car l'en-tête corrompu contamine le corps de la requête. Si votre erreur ressemble à une requête mal formée plutôt qu'à un « invalid key » propre, vérifiez d'abord la présence d'espaces ou de sauts de ligne parasites dans la clé.

Corriger, dans l'ordre

1. Ouvrez Dashboard → API Keys et recopiez la clé. Ne réutilisez pas une valeur issue de l'historique du terminal ou d'un message — copiez directement depuis la page.
2. Vérifiez que le format de l'en-tête correspond exactement : Authorization: Bearer YOUR_API_KEY. Si vous assemblez cette valeur dans un script shell, utilisez printf plutôt que echo — echo ajoute un saut de ligne final que printf n'ajoute pas.
3. Affichez la valeur avant l'envoi de la requête (console.log, print ou journal de débogage) pour confirmer qu'elle n'est pas vide et ne contient ni guillemets, ni espaces, ni sauts de ligne parasites.
4. Testez la clé isolément avec un simple appel curl (voir ci-dessous). Si curl réussit alors que votre application échoue encore, le bug se situe dans la façon dont votre application construit la requête, pas dans la clé elle-même.
5. Vérifiez le code de statut HTTP exact que vous recevez réellement. 401 correspond à cette erreur. 402 signifie que le solde du compte est vide, pas que la clé est erronée. 403 signifie que la clé est valide mais qu'elle n'a pas les droits pour ce modèle spécifique. 429 signifie que vous êtes soumis à une limitation de débit. Aucun de ces trois cas ne doit être traité comme un problème de clé invalide.

Exemple de vérification minimal

Exécutez directement la commande suivante (en remplaçant par votre vraie clé) pour confirmer si la clé elle-même pose problème :

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"}}'

Une clé valide renvoie immédiatement un identifiant de tâche :

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

Une clé incorrecte renvoie le 401 présenté plus haut. Si curl renvoie une réponse avec taskId mais que votre application lève toujours l'erreur « invalid key », le problème se situe dans le code de construction de requête de votre application, pas dans la clé.

Contenu associé

• Authentication docs —— format complet de l'en-tête, guide de renouvellement des clés et référence des codes de statut.
• Dashboard → API Keys —— l'endroit où créer, copier et révoquer des clés.
• Rate limits —— la différence entre 429 et 401 et les conditions de déclenchement.
• Quickstart —— si vous configurez hiapi pour la première fois, vous y trouverez un parcours complet de la première requête.

Questions fréquentes

« invalid API key » et être soumis à une limitation de débit, est-ce la même chose ? Non. Un 401 permission_denied signifie que la clé elle-même n'est pas acceptée. Un 429 avec error_code: "RATE_LIMITED" signifie que la clé est bonne mais que les requêtes arrivent trop vite — voir la documentation sur les limitations de débit pour les seuils.

Je viens de créer une nouvelle clé, mais elle reste invalide — pourquoi ? Assurez-vous que la nouvelle clé a bien été copiée là où la requête est émise. Une nouvelle clé dans le tableau de bord ne corrige pas automatiquement une ancienne valeur codée en dur, une variable d'environnement non définie ou un fichier de configuration non redéployé.

hiapi exige-t-il le mot littéral « Bearer » dans l'en-tête ? Le format documenté et pris en charge est Authorization: Bearer YOUR_API_KEY — utilisez-le toujours. Ne vous fiez pas à un éventuel comportement tolérant que vous auriez observé lors de tests ; un comportement non documenté peut changer sans préavis.

Pourquoi curl fonctionne-t-il alors que mon application échoue ? Si curl réussit avec la même clé, la clé est valide et le problème vient de la façon dont votre application assemble la requête — souvent un préfixe Bearer manquant dans le code, une variable d'environnement lue avant le chargement du .env, ou une clé passée au mauvais paramètre dans une bibliothèque d'encapsulation.

Que signifie error.type: "hiapi_error" ? C'est l'enveloppe d'erreur générique de hiapi, utilisée à la fois pour cet échec d'authentification et pour d'autres erreurs de requête. Consultez error.code (ici permission_denied) pour connaître l'erreur réelle, et non le seul type d'enveloppe.