Erreurs amont 502 / 503 de HiAPI : causes et solutions

Vous appelez POST https://api.hiapi.ai/v1/tasks (ou interrogez GET /v1/tasks/{id}), et au lieu du 200 habituel accompagné d'un taskId, vous recevez 502 Bad Gateway ou 503 Service Unavailable. Les deux sont des réponses 5xx, ce qui signifie que le problème se situe côté serveur ou transport, et non dans votre requête : vous n'avez pas envoyé de paramètres erronés, de clé erronée ni de payload mal formé. Le 503 est le signal « plateforme temporairement indisponible » documenté dans la documentation HiAPI, qui vous indique de réessayer ; le 502 est une réponse de niveau passerelle produite quelque part sur le chemin. Ce guide explique comment le confirmer, comment réessayer en toute sécurité sans refaire le travail, et comment distinguer 502/503 d'un timeout 504 et d'un résultat TASK_FAILED.

À quoi ressemblent réellement 502 ou 503

Vous voyez l'un des éléments suivants sur la ligne de statut HTTP, au lieu du 200 normal :

• 503 Service Unavailable — celui-ci est documenté. La documentation de l'API asynchrone de HiAPI liste le 503 comme « plateforme temporairement indisponible ; réessayez plus tard avec un backoff exponentiel », avec le code métier correspondant TEMPORARILY_UNAVAILABLE (« service de génération temporairement indisponible. Veuillez réessayer plus tard ; si le problème persiste, contactez le support. »). Les erreurs synchrones de HiAPI utilisent une enveloppe JSON plate — la documentation indique pour le cas 400 {"code": 400, "message": "...", "data": null, "error_code": "INVALID_REQUEST"} — donc un 503 renvoyé par l'API devrait également utiliser la même enveloppe, avec error_code: "TEMPORARILY_UNAVAILABLE".
• 502 Bad Gateway — celui-ci ne figure pas parmi les codes de statut documentés par HiAPI. En HTTP standard, un 502 signifie qu'une passerelle ou un proxy a reçu une réponse invalide ou vide du saut suivant qu'il tentait de joindre. Le 502 que vous recevez est donc généré par une passerelle sur le chemin — peut-être la couche edge/CDN, un équilibreur de charge, ou un proxy de votre propre réseau — et non par l'application HiAPI renvoyant son enveloppe JSON habituelle. Le corps de la réponse est généralement une courte page HTML ou texte de passerelle, et ce corps non JSON est en soi un signal : il indique une situation de transport/passerelle plutôt qu'une erreur applicative avec un payload fixe et documenté.

Dans les deux cas, le statut est 5xx : le problème est côté serveur ou transport, pas dans votre requête. C'est l'inverse du 4xx — 400 (paramètres erronés), 401 (clé erronée ; HiAPI renvoie une imbrication {"error": {"code": "permission_denied", "type": "hiapi_error", "request_id": "..."}}) ou 402 (solde insuffisant) — qui nécessitent tous de corriger quelque chose de votre côté. Les 502/503 ne peuvent pas être corrigés en modifiant le payload.

Causes courantes (par ordre de probabilité décroissante)

1. Surcharge temporaire de la plateforme ou fenêtre de maintenance → 503 TEMPORARILY_UNAVAILABLE. C'est un cas attendu et documenté. Il se rétablit de lui-même, et une nouvelle tentative avec backoff réussira.
2. Instabilité momentanée d'une passerelle ou d'un proxy sur le chemin → 502. La couche edge/CDN, un équilibreur de charge ou un proxy de votre propre réseau n'a pas réussi à transmettre la réponse pendant un court instant. Également temporaire.
3. Un pic de trafic a déclenché une limitation. Sous forte charge, vous pouvez au contraire voir 429 RATE_LIMITED (« veuillez réessayer plus tard ; évitez de soumettre immédiatement la même requête »). Si le statut est 429, la solution est de réduire le débit d'envoi, pas de réessayer plus fort.
4. Le backend du modèle demandé est temporairement indisponible. HiAPI l'enregistre au niveau de la tâche comme MODEL_UNAVAILABLE (« veuillez réessayer plus tard, ou changer de modèle ») ; une panne temporaire au niveau plateforme du service de ce modèle peut aussi se manifester par un 503.
5. Ce n'est pas une clé erronée, un corps de requête mal formé ou un solde insuffisant. Ceux-ci sont respectivement 401 / 400 / 402, et aucun ne se manifeste par un 502 ou un 503.

Méthode de résolution, étape par étape

1. Confirmez qu'il s'agit d'un 5xx, et non d'un 4xx. Vérifiez d'abord le code de statut. Les 502/503 relèvent du côté serveur/transport ; les 400, 401, 402, 404, 409, 415, 422 et 429 relèvent de votre côté. S'il s'agit bien d'un 502/503, ne commencez pas à réécrire le corps de la requête — cela n'aiderait que pour un 4xx.
2. Réessayez avec un backoff exponentiel avec jitter. La documentation exige explicitement un backoff exponentiel pour le 503. Le modèle client sûr consiste à commencer à environ 1 seconde, à doubler à chaque tentative (2 s, 4 s, 8 s…), avec un plafond d'environ 30–60 secondes, et à ajouter un jitter aléatoire afin que de nombreux clients ne réessaient pas simultanément. Ces intervalles sont un modèle client recommandé, pas une garantie de délai publiée par HiAPI.
3. Rendez la soumission idempotente. Définissez l'en-tête Idempotency-Key sur POST /v1/tasks (chaîne UTF-8 quelconque, jusqu'à 255 octets). Si un 502/503 vous laisse dans l'incertitude quant à savoir si la tâche a réellement été créée, réessayer avec la même clé est sûr : même clé + même corps de requête renverra le taskId d'origine, avec l'en-tête de réponse Idempotent-Replay: true, sans créer de seconde tâche ni débiter une seconde fois. Les clés sont limitées au périmètre du compte et expirent après 24 heures. La convention complète est décrite dans la documentation de l'API asynchrone unifiée.
4. Ne refaites pas un POST à l'aveugle sans clé. Si vous avez soumis sans Idempotency-Key et avez reçu un 502/503, vous avez peut-être déjà créé une tâche que vous ne voyez pas — vous n'avez pas de taskId à interroger, donc une nouvelle tentative naïve risque de refaire le travail et de débiter deux fois. Ajoutez la clé avant toute nouvelle tentative, quelle qu'en soit l'ampleur.
5. Si le 502/503 survient pendant l'interrogation, contentez-vous de continuer à interroger. Un 5xx renvoyé par GET /v1/tasks/{id} ne change pas l'état de la tâche. Les états terminaux (success / fail) sont fixés dès qu'ils sont atteints et ne basculent jamais de l'un à l'autre, donc il suffit d'interroger à nouveau après un backoff. Vous pouvez aussi enregistrer callback.url pour être notifié à l'état terminal, sans avoir à interroger à travers des 5xx temporaires — la livraison est au moins une fois, donc dédupliquez par taskId.
6. Distinguez cela d'un échec au niveau de la tâche. Si vous recevez plutôt un HTTP 200 avec "status": "fail", ce n'est pas un 502/503 — la tâche a été acceptée, exécutée et a échoué. Traitez TASK_FAILED (« réessayez une fois ; si le problème persiste, contactez le support ») ou TASK_TIMEOUT (« réessayez cette tâche ») selon leurs règles respectives, plutôt que d'effectuer une nouvelle tentative de passerelle à l'aveugle.
7. Si cela persiste, escaladez au lieu de marteler. Si un 502/503 persiste après plusieurs nouvelles tentatives avec backoff sur plusieurs minutes, considérez-le comme un incident temporaire de plateforme, et non comme un problème à résoudre par la force. Arrêtez les nouvelles tentatives agressives et contactez le support en incluant le request_id s'il figure dans le corps de l'erreur. Vous pouvez vérifier que votre compte et la connectivité sont normaux depuis la console HiAPI.

Comparaison entre 502 / 503, 504 et TASK_FAILED

Ces cas sont faciles à confondre, car tous signifient « pas de retour propre », mais ils nécessitent des traitements différents :

Réponse	Code de statut HTTP	Origine	La tâche est-elle facturée ?	Que faire
503 Service Unavailable	503 (documenté)	Plateforme HiAPI — temporairement indisponible ou surchargée	Impossible à déterminer d'après la réponse ; la tâche peut déjà exister	Réessayez avec un backoff et la même Idempotency-Key
502 Bad Gateway	502 (absent de la documentation HiAPI)	Passerelle/proxy sur le chemin (edge, équilibreur de charge ou votre propre proxy)	Impossible à déterminer d'après la réponse	Réessayez de manière idempotente avec un backoff ; si cela ne se produit que depuis votre réseau, soupçonnez un proxy de votre côté
504 Gateway Timeout	504 (absent de la documentation HiAPI)	Passerelle ou proxy sur le chemin qui a cessé d'attendre (504 n'est pas listé dans la documentation HiAPI)	Impossible à déterminer d'après la réponse	Identique au 502 ; HiAPI rapporte ses propres timeouts sous la forme TASK_TIMEOUT
TASK_TIMEOUT	200 + "status": "fail"	HiAPI — la tâche a été exécutée mais a dépassé son budget de temps	Non (le montant pré-réservé est remboursé)	Réessayez cette tâche comme une nouvelle requête
TASK_FAILED	200 + "status": "fail"	HiAPI — la tâche a été acceptée et exécutée, puis a échoué	Non (le montant pré-réservé est remboursé)	Réessayez une fois, puis lisez error.message
429 RATE_LIMITED	429	HiAPI — vous envoyez trop vite	Aucune tâche	Backoff ; ne soumettez pas immédiatement à nouveau
400 / 401 / 402	4xx	HiAPI — côté client (corps/clé/solde erroné)	Non	Corrigez la requête, la clé ou le solde ; réessayer ne servirait à rien

Règle en une phrase : 502/503/504 sont des erreurs de transport HTTP qui ne portent aucun résultat de tâche ; tandis que TASK_FAILED / TASK_TIMEOUT arrivent sous la forme d'un HTTP 200 avec "status": "fail" et un objet error. Les premiers signifient « vous ne savez pas si la requête a été reçue » ; les seconds signifient « la requête a été reçue, la tâche a été exécutée, et elle a échoué ».

Exemple de vérification minimal

Utilisez une soumission propre pour prouver que votre clé et la connectivité fonctionnent, et isoler le 502/503 comme un problème temporaire. Utilisez un id de modèle dont vous êtes sûr qu'il fonctionne (par exemple gpt-image-2/text-to-image), et incluez l'en-tête Idempotency-Key afin que les nouvelles tentatives soient sûres :

# A healthy submit returns 200 with a taskId. If this works but a specific
# call just 502/503'd, that 502/503 was transient — not your setup.
curl -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-job-0001" \
  -d '{"model":"gpt-image-2/text-to-image","input":{"prompt":"a red bicycle on a white background"}}'

# Then poll the task you just created (swap in the returned id):
curl -sS https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Si la soumission elle-même renvoie 200 et un taskId, cela signifie que votre authentification et le chemin réseau fonctionnent, et que le 502/503 précédent était une situation serveur/transport temporaire — réessayez l'appel qui a échoué (réutiliser la même Idempotency-Key renverra la tâche d'origine, et non une tâche en double). Si la soumission renvoie plutôt 401 ou 400, il s'agit d'un problème côté client, et non d'un 502/503.

Lectures associées

• Timeout de tâche HiAPI et erreur 504 : comment corriger — pourquoi un 504 brut ne provient pas de HiAPI, et ce que signifie TASK_TIMEOUT.
• Erreur TASK_FAILED de HiAPI : causes et solutions — traitement des tâches qui renvoient 200 + "status": "fail".
• Quand un job hiapi /v1/tasks se bloque ou expire : diagnostic et nouvelles tentatives — analyse approfondie des intervalles d'interrogation et des stratégies de nouvelle tentative.
• Comment corriger l'erreur de limite de débit (429) de HiAPI — lorsque le vrai problème est le débit d'envoi et non la disponibilité.
• Pourquoi les requêtes HiAPI échouées sont-elles quand même facturées ? — comment fonctionnent la pré-réservation et le remboursement des tâches échouées.

Questions fréquentes

Un 502 ou un 503 est-il de ma faute ? Non. Tous deux sont des réponses 5xx, qui relèvent du côté serveur ou transport. Votre clé API et votre corps de requête ne sont pas les déclencheurs — ce sont les 4xx (400/401/402) qui relèvent de vous et peuvent être corrigés. La bonne réponse à un 502/503 est une nouvelle tentative idempotente, pas une modification du code.

Quelle est la différence entre 502 et 503 sur HiAPI ? Le 503 est le code « plateforme temporairement indisponible » documenté par HiAPI (error_code: TEMPORARILY_UNAVAILABLE), provenant de la plateforme elle-même. Le 502 ne figure pas parmi les codes de statut documentés par HiAPI ; en HTTP standard, il est émis par une passerelle ou un proxy sur le chemin lorsqu'une réponse invalide est renvoyée en amont. Tous deux sont temporaires et nécessitent une nouvelle tentative avec backoff, mais un 502 peut aussi pointer vers un proxy de votre propre réseau.

En quoi un 503 diffère-t-il d'un 504 ? Le 503 signifie que le service est actuellement temporairement indisponible ou surchargé. Le 504 Gateway Timeout signifie que quelque part l'attente d'une réponse a duré trop longtemps. La documentation HiAPI ne liste pas le 504 ; si vous le voyez, une passerelle ou un proxy sur le chemin a abandonné l'attente. Le propre état « trop long » de HiAPI est le résultat de tâche TASK_TIMEOUT (HTTP 200 + "status": "fail"). Voir le guide sur le 504 ci-dessus.

Comment distinguer un 502/503 d'un résultat TASK_FAILED ? Regardez le code de statut HTTP. Un 502/503 est une erreur HTTP sans payload de tâche. Un TASK_FAILED revient sous la forme d'un HTTP 200 avec "status": "fail" et un objet error — la tâche a été acceptée et exécutée. Utilisez une nouvelle tentative avec backoff pour un 502/503 ; pour un TASK_FAILED, réessayez une fois, puis lisez error.message.

Réessayer après un 502/503 me facturera-t-il deux fois ou créera-t-il une tâche en double ? Non, si vous envoyez l'en-tête Idempotency-Key sur POST /v1/tasks. Réutiliser la même clé + le même corps de requête renvoie le taskId d'origine (Idempotent-Replay: true) sans créer de tâche en double. De plus, les tâches échouées ne sont jamais facturées — dès qu'une tâche atteint un état terminal d'échec, le montant pré-réservé lors de la création est intégralement remboursé.

Combien de temps dois-je attendre avec un backoff, et quand dois-je escalader ? Utilisez un backoff exponentiel avec jitter (par exemple 1 s, 2 s, 4 s, 8 s, avec un plafond et un caractère aléatoire). Si le 502/503 continue de revenir après plusieurs nouvelles tentatives sur plusieurs minutes, arrêtez les nouvelles tentatives agressives et contactez le support en incluant le request_id du corps de l'erreur — un 5xx persistant signifie généralement un incident temporaire de plateforme, et non un problème qu'une boucle de nouvelles tentatives plus rapide peut résoudre.

Dois-je modifier le payload de la requête lorsque je vois un 502/503 ? Non. Un 502/503 n'est pas une erreur de validation, donc modifier les paramètres n'aidera pas et pourrait masquer la véritable cause temporaire. Gardez la requête inchangée, ajoutez la Idempotency-Key si ce n'est pas déjà fait, puis réessayez avec un backoff.