Que faire lorsque HiAPI renvoie 402 solde insuffisant (INSUFFICIENT_QUOTA) ? Causes et étapes de correction

Lors d'un appel à l'API HiAPI, il arrive que l'on reçoive une réponse HTTP 402 avec, dans le corps de la réponse, un champ error_code égal à INSUFFICIENT_QUOTA. Cela signifie que le solde de Credits du compte est épuisé, et cela n'a rien à voir avec la validité de la clé API, le format de la requête ou un éventuel déclenchement de limitation de débit. La tâche est rejetée avant sa création, donc aucune facturation n'a lieu. La correction est presque toujours la même : se rendre sur la page de facturation pour ajouter des Credits au compte, puis réessayer à l'identique la requête qui vient d'échouer.

Causes fréquentes

1. Le solde est déjà à 0. Les nouveaux comptes bénéficient de Credits offerts à l'inscription ; une fois ces Credits et les recharges ultérieures épuisés, tout appel de création de tâche renvoie 402 jusqu'à ce que le solde redevienne positif.
2. Appels intensifs sur une courte période, consommation du solde plus rapide que prévu. Les modèles vidéo sont généralement facturés à la seconde de sortie ; enchaîner plusieurs clips vidéo consomme souvent bien plus de Credits que le même nombre de tâches d'image, ce qui fait facilement tomber le solde à zéro sans qu'on s'en rende compte.
3. Confondre 401 ou 429 avec 402. Examinez directement le code de statut HTTP et le champ error_code : 401 (error_code du type permission_denied, clé invalide ou désactivée) et 429 (error_code: RATE_LIMITED, requêtes trop rapides) ressemblent tous deux à un « échec d'appel », mais leur correction est totalement différente de celle du 402 ; mélangés dans les logs, ils orientent facilement le diagnostic dans la mauvaise direction.

Étapes de correction

1. Vérifier d'abord le solde. Ouvrez la page de facturation de la console et consultez le solde de Credits actuel ; cette étape permet de confirmer directement si le 402 est réellement dû à un problème de solde.
2. Recharger le compte. Toujours depuis la page de facturation, ajoutez des Credits ; il n'y a aucune étape de « déblocage » supplémentaire, et dès que le solde redevient positif, la création de tâches réussit immédiatement.
3. Réessayer la requête à l'identique. Aucun code ni paramètre à modifier. Les mêmes prompt, model et autres champs réussiront directement une fois le solde suffisant ; si vous ne savez pas combien coûte approximativement un appel à un modèle donné, consultez d'abord la page de tarifs.
4. Configurer une alerte de solde pour éviter la prochaine fois. Les paramètres de la console proposent une fonction d'alerte de solde (Balance Alerts) : un e-mail est envoyé lorsque le solde passe sous le seuil que vous avez défini, ce qui permet de recharger avant l'épuisement réel.

Exemple de vérification minimal

La requête minimale suivante permet de confirmer de façon autonome que le problème vient du solde du compte, en écartant toute interférence du modèle ou du SDK :

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

Lorsque le solde est vide, la structure renvoyée est la suivante :

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

Après recharge, la même requête renvoie une réponse normale de création de tâche :

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

Notez que le champ code correspond au code de statut HTTP, que error_code est une valeur stable servant aux branchements conditionnels, et que data vaut toujours null en cas d'échec de création.

Liens internes associés

• Tarifs HiAPI
• Facturation et gestion du solde
• Créer une tâche asynchrone (documentation API)

FAQ

Comment le solde a-t-il pu s'épuiser d'un coup, sans aucune alerte auparavant ? Par défaut, on ne découvre l'insuffisance de solde que lorsqu'une tâche échoue réellement avec un 402. Activez l'alerte de solde (Balance Alerts) dans les paramètres de la console : un e-mail est envoyé lorsque le solde passe sous le seuil défini, ce qui permet de recharger à l'avance.

Un 402 peut-il interrompre une tâche déjà en cours ? Non. INSUFFICIENT_QUOTA est renvoyé au stade de la création de la tâche ; à ce moment la tâche n'existe pas encore, il ne peut donc pas être question d'interrompre une tâche en cours d'exécution : cela bloque uniquement la création de nouvelles tâches.

Les requêtes échouées à cause d'un 402 sont-elles facturées ? Non. La vérification du solde a lieu avant la création effective de la tâche ; un 402 signifie que la tâche n'a pas été créée et qu'aucun Credit n'a été débité du compte.

Un 402 et une limitation de débit (429) sont-ils la même chose ? Non. La limitation de débit renvoie un 429 avec error_code égal à RATE_LIMITED, signifiant que les requêtes sont envoyées trop vite ; un 402 signifie que le solde de Credits du compte est insuffisant, indépendamment de la fréquence des requêtes, et les corrections diffèrent.

Comment le savoir avant l'épuisement du solde ? Ouvrez la page de facturation de la console : vous y voyez le solde de Credits actuel et l'historique complet des dépenses, et vous pouvez y définir le seuil d'alerte de solde.