Pourquoi une requête HiAPI échouée peut-elle quand même entraîner une facturation ?

Symptôme

Vous envoyez une tâche de génération via POST à https://api.hiapi.ai/v1/tasks, puis vous interrogez avec GET /v1/tasks/:id, et vous obtenez "status": "fail" accompagné d'un objet error, par exemple {"code": "TASK_FAILED", "message": "task failed"}. Le code de statut HTTP de cet appel d'interrogation est bien 200 — HiAPI encapsule l'information d'échec dans le corps JSON, et non dans le code de statut. Comme cette tâche est bien passée par queued → handling avant d'échouer, on peut facilement croire que cette tentative a été facturée comme un appel normal. En réalité, le passage de la tâche à l'état terminal fail ne signifie pas qu'elle a été facturée — mais si vous consultez votre solde avant que le remboursement n'arrive, la pré-réservation effectuée à la création donnera effectivement l'impression que de l'argent a été débité.

Causes fréquentes

1. Confondre la « pré-réservation » avec la « facturation ». HiAPI pré-réserve le coût estimé de la tâche dès sa création, avant même qu'elle ne commence réellement à s'exécuter. Cette pré-réservation se reflète immédiatement dans votre solde — mais ce n'est pas encore une facturation.
2. Consulter le solde pendant que la tâche est en cours. Entre queued/handling et l'état terminal, cette pré-réservation est censée rester « en attente » ; c'est un comportement voulu. Seul l'état terminal (success ou fail) la solde.
3. Confondre « le service en aval a réellement tourné mais a échoué » et « rejeté dès la phase de création ». Une tâche qui atteint status: "fail" (par exemple error.code: "TASK_FAILED") a réellement été créée, a réellement tourné, et a échoué en aval — la documentation HiAPI précise explicitement qu'après le passage à cet état terminal, le montant pré-réservé est automatiquement remboursé intégralement. En revanche, une requête qui n'a jamais obtenu de taskId — par exemple un 402 INSUFFICIENT_QUOTA retourné en synchrone — a été rejetée avant même l'existence de la tâche, et rien n'a donc été pré-réservé. De l'extérieur, les deux cas ressemblent à un « échec », mais seul le premier a réellement touché au mécanisme de pré-réservation.
4. Mauvais usage de Idempotency-Key. Rejouer avec la même clé et le même corps de requête ne renvoie que le taskId d'origine, sans créer de tâche ni débiter une seconde fois. En revanche, rejouer avec la même clé mais un corps différent renvoie directement 422 IDEMPOTENCY_KEY_MISMATCH dès la phase de création ; renvoyer une requête avec la même clé alors que le premier appel n'est pas encore traité renvoie 409 IDEMPOTENCY_KEY_PROCESSING. Aucun de ces deux chemins ne crée de tâche facturable.

Étapes de correction

1. Interrogez GET /v1/tasks/:id et regardez directement data.status — ne devinez pas le résultat de la facturation à partir d'une simple capture du solde à un instant donné. queued, handling et archiving sont des états non terminaux ; seuls success et fail sont des états terminaux.
2. Si data.status vaut "fail", il s'agit d'un résultat qui sera remboursé. Consultez data.error.code (par exemple TASK_FAILED) pour comprendre la cause, puis vérifiez à nouveau le solde — le remboursement est crédité automatiquement dès que la tâche atteint cet état terminal.
3. Si l'appel POST /v1/tasks lui-même renvoie un code non 2xx (400/402/409/415/422) et que le corps ne contient pas de taskId, il n'y a aucune tâche à rembourser — car aucune tâche n'a été créée ni facturée. Le cas précis d'un solde insuffisant se manifeste par un error_code: "INSUFFICIENT_QUOTA" dans une réponse 402.
4. Rendez-vous dans le back-office de facturation HiAPI pour vérifier la paire de transactions « pré-réservation — remboursement », plutôt que de vous fier à un chiffre de solde à un instant donné.
5. Pour réessayer une tâche échouée, attribuez une nouvelle Idempotency-Key à cette véritable nouvelle tentative. Ne rejouez pas avec l'ancienne clé en changeant le corps de requête (cela déclencherait une 422), et n'envoyez pas une seconde fois avec la même clé pendant que la première requête est encore en cours de traitement (cela déclencherait une 409).
6. Si vous confirmez que la tâche a bien atteint l'état terminal fail mais que le montant pré-réservé n'a toujours pas été remboursé après un certain temps, cela dépasse le cadre de ce mécanisme de remboursement automatique — contactez directement le support, ne partez pas du principe que cela se rétablira tout seul.

Exemple de vérification minimal

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": { "prompt": "a minimalist desk setup, studio lighting" }
  }'

Ici, le champ model comporte le suffixe de routage /text-to-image. À la date de rédaction de cet article, dans l'index des modèles HiAPI, le groupe gpt-image-2 ne contient que des entrées avec suffixe de routage (/text-to-image, /image-to-image), sans entrée avec l'id nu. Pour savoir s'il faut mettre un suffixe et lequel, référez-vous impérativement aux entrées availability: "online" de cet index de modèles en temps réel, et ne copiez pas la syntaxe d'autres modèles ou d'anciennes documentations.

Une fois le taskId retourné obtenu, interrogez :

curl -s https://api.hiapi.ai/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Une tâche échouée et remboursée ressemble à ceci :

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "gpt-image-2/text-to-image",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_FAILED", "message": "task failed" }
  }
}

Liens internes associés

• Back-office de facturation HiAPI
• API de tâches asynchrones unifiée HiAPI : codes d'erreur et états
• Tâche HiAPI bloquée ou expirée : guide de diagnostic et de nouvelle tentative
• Guide de correction des erreurs HiAPI « model not found » / « model not available »

FAQ

Si une tâche d'image ou de vidéo échoue, HiAPI me facture-t-il ? Non. Dès que la tâche atteint l'état terminal fail, le montant pré-réservé à la création est automatiquement remboursé intégralement.

Mon solde a baissé immédiatement après la soumission, puis la tâche a échoué, pourquoi le solde n'est-il pas revenu ? Cette baisse correspond à la pré-réservation effectuée à la création, pas à une facturation. Elle est soldée automatiquement lorsque la tâche atteint son état terminal — remboursée en cas de fail, réellement consommée en cas de success.

Quelle différence entre une erreur 402 et un échec de tâche ? 402 INSUFFICIENT_QUOTA signifie que la tâche n'a jamais été créée : il n'y a donc rien à pré-réserver ni à rembourser. En revanche, une tâche qui a obtenu un taskId et dont le status est ensuite passé à "fail" a réellement été créée, a réellement tourné, puis a échoué en aval ; HiAPI rembourse automatiquement cette pré-réservation.

Réessayer avec le même Idempotency-Key me fera-t-il payer deux fois ? Non. Rejouer avec la même clé et le même corps de requête ne renvoie que le taskId d'origine, sans créer de nouvelle tâche. Si le corps de requête change avec la même clé, une erreur 422 IDEMPOTENCY_KEY_MISMATCH est directement renvoyée, sans créer de tâche en double.

Où consulter les enregistrements de pré-réservation et de remboursement ? Dans les factures et l'historique des transactions du back-office de facturation HiAPI.