Délais d'expiration des tâches HiAPI et erreurs 504 : guide de diagnostic et de correction

Les tâches HiAPI, dans la réponse renvoyée par GET /v1/tasks/{id}, présentent parfois "status": "fail" et "error": {"code": "TASK_TIMEOUT", "message": "Task timed out"} — notez que le code HTTP de cette réponse elle-même est 200 : il s'agit d'un véritable état d'échec documenté par HiAPI, qui signifie que la tâche a commencé à s'exécuter mais n'a pas pu se terminer dans son budget de temps interne. Si ce que vous voyez n'est pas ce JSON, mais qu'un client renvoie directement un 504 Gateway Timeout brut, alors ce n'est pas du tout l'API HiAPI qui l'a renvoyé : 504 ne figure dans aucune liste de codes de statut documentés par HiAPI. Cet article traite séparément ces deux cas : comment lire et corriger un véritable TASK_TIMEOUT ; et d'où peut bien sortir un 504.

À quoi ressemble exactement l'erreur

Le flux de tâches HiAPI est asynchrone : POST /v1/tasks renvoie immédiatement un taskId, puis vous interrogez GET /v1/tasks/{id} pour obtenir le résultat. Le champ error n'apparaît que lorsque status atteint un état terminal. Un véritable dépassement de délai ressemble à ceci :

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-xxxxxxxx",
    "model": "gpt-image-2",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": { "code": "TASK_TIMEOUT", "message": "Task timed out" }
  }
}

Notez que le code HTTP de cette réponse est 200 — la requête d'interrogation elle-même a réussi ; c'est la tâche qui a échoué, et les détails de l'échec se trouvent dans data.error. Cela diffère des échecs synchrones de la phase de création (par exemple un solde insuffisant donne 402, un corps de requête incorrect donne 400) : ce type d'erreur est renvoyé immédiatement lors de l'appel initial POST /v1/tasks, alors que la tâche n'a même pas encore été créée. TASK_TIMEOUT ne peut se produire que sur une tâche créée avec succès.

Et 504, dans la plupart des cas, n'est pas du tout un corps de réponse : c'est un code de statut qu'un proxy, un répartiteur de charge ou certaines bibliothèques clientes HTTP émettent eux-mêmes lorsqu'ils renoncent à attendre une réponse. Les codes de statut HTTP documentés par HiAPI sont 200, 400, 402, 404, 409, 415, 422, 503 — 504 n'y figure pas. Si ce que vous voyez est en réalité 401, c'est un autre problème (clé API invalide ou désactivée, pas un dépassement de délai) et cela sort du cadre de cet article.

Causes courantes (par ordre de probabilité)

1. Un véritable dépassement de délai au niveau de la tâche. Le modèle a reçu la tâche, mais n'a pas pu la terminer dans son budget de temps interne. C'est exactement le scénario TASK_TIMEOUT présenté ci-dessus, plus fréquent sur les tâches plus lourdes — durée de vidéo plus longue, résolution plus élevée, ou surcharge temporaire du modèle lui-même.
2. Un 504 provenant de l'extérieur de HiAPI. La grande majorité des signalements de « 504 » sont en réalité le read timeout de votre propre client (la bibliothèque HTTP abandonne faute d'attendre), ou le proxy d'entreprise, le VPN, le répartiteur de charge entre vous et api.hiapi.ai qui coupe la connexion selon ses propres paramètres de délai d'expiration. Puisque HiAPI ne renvoie jamais de 504, il s'agit d'un problème de configuration côté client ou réseau, pas d'une panne de HiAPI.
3. Une tâche encore en cours prise à tort pour un dépassement de délai. queued, handling, archiving sont tous des états non terminaux ; à ce moment-là, le champ error n'existe tout simplement pas. Voir une seule fois un statut différent de success lors d'une interrogation ne signifie pas qu'il y a dépassement de délai.

Étapes de correction

1. Récupérez la tâche par taskId et lisez directement status et error.code. Ne devinez pas la cause à partir d'un message d'exception vague dans le code client — appelez GET /v1/tasks/{id} et examinez le corps de la réponse lui-même.
2. Si status vaut "fail" et que error.code vaut "TASK_TIMEOUT" : réessayez. La correction documentée est aussi simple que cela — soumettez à nouveau avec un nouvel appel POST /v1/tasks (vous obtenez un nouveau taskId), sans avoir besoin de changer de compte ni de clé.
3. Si la tâche elle-même est lourde, vérifiez d'abord les paramètres d'entrée. Une durée de vidéo plus longue, une résolution plus élevée, ou un prompt très volumineux/complexe rapprochent le modèle de sa limite de budget de temps. Si la même configuration dépasse systématiquement le délai, essayez une résolution/durée plus faible, ou changez de modèle.
4. Si ce que vous voyez est en réalité un 504 brut (sans corps de réponse JSON contenant error.code), le problème est en dehors de HiAPI. Vérifiez le read timeout configuré dans votre client HTTP ou votre SDK — beaucoup de valeurs par défaut sont trop courtes (10-30 secondes) ; dans un flux asynchrone, il ne faut de toute façon pas bloquer sur une longue requête, mais interroger séparément. Vérifiez aussi si vous passez par un proxy d'entreprise, une passerelle VPN ou un répartiteur de charge, qui peuvent couper la connexion selon leurs propres paramètres de délai, indépendamment de HiAPI.
5. Si status est encore queued, handling ou archiving, ne réessayez pas tout de suite. Rien n'a réellement échoué. Pour un diagnostic plus complet, consultez le guide de diagnostic des tâches hiapi bloquées / en dépassement de délai (en anglais).

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" \
  -d '{
    "model": "gpt-image-2",
    "input": {
      "prompt": "a single red apple on a white background, studio lighting"
    }
  }'

Cela renvoie immédiatement un taskId :

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

Puis interrogez-le :

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

Une tâche normale finira par renvoyer "status": "success" et le résultat. Une tâche réellement expirée renvoie la structure TASK_TIMEOUT présentée plus haut. Si vous obtenez un 504 au niveau de la connexion, sans aucun corps de réponse JSON, cela signifie que la réponse n'a pas pu revenir depuis l'API HiAPI — vérifiez les paramètres de délai d'expiration de votre client et le chemin réseau selon les étapes ci-dessus, plutôt que de suspecter un problème de compte.

Liens internes associés

• Console HiAPI
• Créer une tâche asynchrone (documentation API)
• Guide de diagnostic des tâches hiapi bloquées / en dépassement de délai (en anglais)

FAQ

Le TASK_TIMEOUT de HiAPI et le HTTP 504 Gateway Timeout sont-ils la même chose ? Non. TASK_TIMEOUT est un code d'erreur documenté par HiAPI, qui apparaît dans une réponse 200 normale et indique que le status de la tâche elle-même est passé à fail, autrement dit que la tâche a dépassé son délai en interne. 504 est un code de statut HTTP générique émis par certains proxies, répartiteurs de charge ou bibliothèques clientes HTTP lorsqu'ils renoncent à attendre une réponse ; l'API HiAPI ne documente ni ne renvoie jamais de 504, donc le 504 littéral que vous voyez provient forcément d'un maillon entre vous et HiAPI, ou de votre propre client, qui a renoncé à attendre — ce n'est pas une panne du service HiAPI.

Que faire en cas de TASK_TIMEOUT ? Il suffit de soumettre une nouvelle tâche. La correction documentée de TASK_TIMEOUT est de réessayer ; il n'y a pas d'étape de déverrouillage séparée, et si ce n'est pas la même entrée qui expire de façon répétée, il n'est pas nécessaire de modifier le prompt ni les paramètres.

Réessayer une tâche expirée entraîne-t-il une double facturation ? Le tableau des codes d'erreur documentés par HiAPI ne le précise pas explicitement. Si cela est important pour vous, vérifiez l'historique d'utilisation dans la console avec ce taskId précis, plutôt que de vous fier à une supposition.

Mon client HTTP a levé une exception de timeout, pas un TASK_TIMEOUT au format JSON : est-ce la même chose ? Non. Un timeout de votre propre client (par exemple le ReadTimeout d'une bibliothèque HTTP, ou un 504 renvoyé par un proxy d'entreprise) signifie que votre connexion a abandonné avant même d'obtenir une quelconque réponse de HiAPI ; cela ne signifie pas que la tâche elle-même a échoué. Puisque /v1/tasks est asynchrone, la correction habituelle consiste à augmenter le read timeout du client (ou simplement à ne pas bloquer sur le POST initial) et à interroger séparément GET /v1/tasks/{id} jusqu'à voir un état terminal.

La tâche est en queued ou handling depuis plusieurs minutes, sans erreur ; est-ce un dépassement de délai ? Pas encore. queued, handling, archiving sont tous des états non terminaux ; le champ error n'apparaît que lorsque status passe à fail. Si la tâche ne converge vraiment jamais, consultez le guide de diagnostic des tâches hiapi bloquées / en dépassement de délai (en anglais) pour une décomposition complète des causes d'état en cours, comme l'accumulation en file d'attente.