HiAPI renvoie 403 sans accès au modèle : guide de diagnostic et de résolution

Lors d'un appel à l'interface /v1/tasks de HiAPI, si vous recevez un HTTP 403, le corps de la réponse se présente généralement ainsi : {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Cela signifie que votre clé API est elle-même valide et que l'authentification a réussi, mais que cette clé n'est pas autorisée à appeler le modèle ou l'interface que vous demandez — c'est un problème distinct du 401 « clé invalide ou absente » : le 401 signifie que l'identité n'a même pas été reconnue, le 403 que l'identité est reconnue mais que cette clé n'est pas autorisée à utiliser la ressource demandée. La correction de la plupart des 403 est directe : vérifier la correspondance entre la clé et le modèle, puis réessayer avec une clé disposant des autorisations.

Causes fréquentes

1. La clé API n'est pas autorisée à utiliser le modèle demandé — la documentation officielle définit le 403 comme « la clé API n'a pas cette autorisation » ; c'est le scénario le plus courant, qui survient généralement lorsqu'une même clé appelle un modèle hors de son périmètre d'autorisation.
2. Mauvaise clé utilisée — par exemple, vous auriez dû utiliser la clé principale mais vous avez employé par erreur une clé au périmètre plus restreint d'un autre compte ou projet ; lors du copier-coller, des espaces superflus ou une troncature peuvent aussi s'introduire.
3. Confusion entre « clé invalide » (401) et « clé sans autorisation » (403) — les deux messages d'erreur peuvent contenir des termes liés aux « autorisations » ; les diagnostiquer avec la même approche mène dans la mauvaise direction. Voir ci-dessous comment les distinguer.

Étapes de résolution

1. Confirmer d'abord qu'il s'agit bien d'un 403 et non d'un 401 — regardez le code de statut HTTP lui-même, pas seulement le texte du message d'erreur, car le code d'erreur permission_denied peut apparaître aussi bien en 401 qu'en 403 ; le critère de distinction est le code de statut, pas le libellé.
2. Vérifier l'appartenance de cette clé dans la gestion des clés API — assurez-vous que la clé réellement utilisée dans la requête est bien celle attendue, et non une clé d'un compte de test, d'un ancien projet ou d'un tiers.
3. Vérifier que le modèle actuel figure dans le périmètre d'utilisation de cette clé — consultez la documentation d'authentification et la tarification HiAPI pour confirmer que le modèle existe bien et qu'il est dans votre périmètre d'appel ; si l'ID du modèle est mal orthographié ou a été retiré, l'erreur devrait être un autre code et non permission_denied — ce point aide à distinguer le type de problème.
4. Remplacer par une clé dont les autorisations sont confirmées et réessayer avec tous les autres paramètres identiques, pour vérifier si le problème disparaît avec le changement de clé.
5. Si, après vérification, la clé et le modèle sont corrects mais que le 403 se reproduit systématiquement, notez le request_id du corps de la réponse et contactez le support ; ne réessayez pas la même requête à répétition sans avoir confirmé la cause.

Exemple de vérification minimal

Ci-dessous, une requête déclenchant un 403 et une nouvelle tentative après correction, montrant la structure réelle des réponses dans les deux états (remplacez MODEL_ID par le modèle que vous appelez réellement et que vous soupçonnez de manquer d'autorisation) :

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

Réponse en cas de manque d'autorisation :

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

Nouvelle tentative avec une clé disposant des autorisations, les autres paramètres inchangés :

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

On remarque que les structures des deux corps de réponse diffèrent : les erreurs de niveau authentification/autorisation comme le 403 sont uniformément encapsulées dans un objet error ; en revanche, les erreurs produites après que la clé a passé le contrôle d'autorisation et que l'on entre réellement dans les règles métier spécifiques (par exemple un 402 pour solde insuffisant) renvoient une structure à plat de type code / data / message. Selon la structure observée, on peut globalement déterminer si le problème se situe au niveau authentification/autorisation ou au niveau des règles métier spécifiques.

Liens internes associés

• Gestion des clés API
• Documentation d'authentification
• Tarification HiAPI

FAQ

Quelle est la différence exacte entre 403 et 401 ? Le 401 indique que la clé elle-même est invalide, ou que la requête ne contient aucune clé — l'étape d'authentification de l'identité n'a même pas été franchie. Le 403 indique que l'authentification a réussi (la clé elle-même est valide), mais que cette clé n'est pas autorisée à utiliser le modèle ou la ressource demandée. La structure des corps de réponse est identique (tous deux encapsulent un objet dans error.code) ; le critère de distinction est le code de statut HTTP lui-même, pas le texte du message d'erreur.

Toujours 403 après avoir changé de clé : est-ce un problème de compte ? Vérifiez d'abord que la nouvelle clé appartient bien au même compte ou projet disposant des autorisations, et qu'aucun espace, saut de ligne ou troncature superflus ne s'est introduit lors du copier-coller. Si le problème se reproduit après vérification, contactez le support en fournissant le request_id du corps de la réponse.

Le 403 est-il dû à un solde insuffisant ? Non. Un solde insuffisant correspond à un autre code d'erreur (INSUFFICIENT_QUOTA, HTTP 402), ce sont deux choses distinctes des autorisations — le 403 indique uniquement « cette clé a-t-elle le droit d'appeler ce modèle », indépendamment du solde du compte.

La présence du mot « autorisation » dans le message d'erreur implique-t-elle forcément un 403 ? Pas nécessairement. Le code d'erreur permission_denied peut apparaître aussi bien en 401 qu'en 403 ; on ne peut pas se fier au seul mot-clé, il faut regarder directement le code de statut HTTP lui-même.