GPT Image 2.5 is live — OpenAI's newest image model, targeted edits that leave the rest of the frame alone
Tous les guides

· reAPI Team

Erreurs API 500 : quand réessayer une requête vidéo

Gère les erreurs API 500 sans dupliquer les tâches vidéo payantes. Vérifie si la soumission a été acceptée, récupère les ID de tâche, limite les nouvelles tentatives et reprends les workflows en toute sécurité.

Erreurs API 500 : quand réessayer une requête vidéo

Un clic, un message d’erreur, puis un autre clic. Dans une application vidéo, cela peut suffire à créer deux générations payantes alors que l’interface affiche toujours un échec.

Prenons une requête hypothétique : le serveur accepte la première soumission, démarre une tâche et perd la réponse pendant son retour vers le client. Le client reçoit une erreur et soumet de nouveau. Si le point de terminaison crée une nouvelle tâche pour chaque soumission acceptée, les deux jobs peuvent se poursuivre. Le second clic n’a pas réparé la première réponse ; il a demandé une autre vidéo.

C’est la difficulté pratique des erreurs API 500. Les recommandations d’AWS sur les nouvelles tentatives avertissent qu’une réponse en échec ou un délai d’attente dépassé ne prouve pas que l’opération n’a eu aucun effet de bord.[1] Avant de relancer une génération, cherche ce que faisait la requête en échec et quelles preuves de son acceptation subsistent.

Retrouve la requête en échec

Un message tel que « Request failed with status code 500 » indique un résultat HTTP, pas l’état de la vidéo. MDN définit le code 500 comme une situation inattendue du serveur qui a empêché l’exécution de la requête.[2] Il ne t’indique pas quel composant a échoué, ne prouve pas que chaque entrée était valide et ne garantit pas que l’attente résoudra le problème.

Consulte la méthode et l’URL dans le journal du client. Un échec du POST de génération a des conséquences différentes d’un échec lors de la récupération d’une tâche existante. Le téléchargement d’un fichier peut échouer après la réussite de ces deux opérations. Une interface qui regroupe les trois cas sous « échec de génération » perd la distinction nécessaire à la reprise.

Conserve l’heure UTC, le modèle, le statut, le corps de la réponse et tout identifiant de requête ou de tâche disponible. Masque les identifiants d’accès avant de partager les journaux. Si la réponse est du HTML au lieu du format d’erreur API documenté, conserve aussi cette information ; ne déduis pas une défaillance du modèle à partir d’une page d’erreur générique.

Pour le premier clic hypothétique, la question est de savoir si tu as un ID de tâche. Cherche la réponse à la soumission enregistrée par ton serveur, la sortie du workflow concerné et tout enregistrement de rappel documenté. Vérifie le compte ou le projet qui a réellement envoyé la requête. Un autre compte de tableau de bord ne permet pas de déterminer si cette soumission a créé une tâche.

Avec un ID de tâche, reprends à partir de cette tâche

Si tu as récupéré l’identifiant, utilise l’opération de lecture documentée par le fournisseur. Sur reAPI, GET /api/v1/tasks/{id} récupère la tâche sans consommer de crédits.[3] C’est le bon moyen de reprendre l’observation ; renvoyer le corps initial de génération crée une soumission distincte.

Lis l’état de la tâche dans la réponse. reAPI renvoie HTTP 200 lorsqu’une tâche est trouvée, y compris lorsque son état est failed.[4] HTTP 200 ne signifie donc pas que la vidéo a réussi. De même, un 500 lors de la consultation ne prouve pas que la vidéo a échoué. Cela signifie que cette consultation ne t’a pas fourni de réponse exploitable.

Traite une tâche terminée à l’aide des champs de sortie documentés. Enregistre le fichier dont tu as besoin au lieu de laisser l’application attendre une seconde génération. Une tâche en cours reste sous observation. Pour une tâche en échec, lis l’erreur et les informations de règlement avant de décider si une nouvelle tentative est pertinente.

La tâche en échec et sa facturation sont liées, mais distinctes. reAPI documente le remboursement des échecs et des cas propres à certains modèles où un contrôle de sécurité après génération peut bloquer une sortie après qu’une génération facturable a eu lieu.[3] Conserve l’enregistrement d’utilisation réel de la tâche. Une bannière générale « erreur serveur » ne prouve pas que tous les frais doivent disparaître ; la facturation des générations échouées doit être évaluée à partir de l’état final de la tâche et de la politique applicable.

Sans ID, laisse l’acceptation en suspens

Le cas le plus difficile est celui du premier clic sans réponse de soumission exploitable. Attribue explicitement un état non résolu à cette opération dans ton application. Par exemple, une valeur interne acceptance_unknown peut la distinguer d’un travail qui n’a jamais été envoyé et d’un travail dont le fournisseur a confirmé l’échec. Il s’agit d’un état suggéré pour l’application, pas d’un champ renvoyé par toutes les API.

Conserve un ID d’opération local stable et désigne un responsable de la reprise. Cette personne peut rapprocher les éléments réellement fournis par l’intégration : réponses enregistrées, rappels, historique des tâches autorisé ou résultats obtenus auprès du support. Si une tâche est identifiée plus tard, rattache-la à l’opération initiale et reprends à partir de là.

Une colonne locale d’ID de tâche vide prouve uniquement que ton application n’a pas enregistré d’ID. La réponse a pu être perdue après l’acceptation. De même, ton ID d’opération local n’est pas automatiquement transmis au fournisseur et ne fait pas dédupliquer les requêtes par son point de terminaison de création. Il aide à organiser tes éléments de preuve ; ce n’est pas la preuve d’une exécution exactement une fois.

Sois tout aussi prudent avec un en-tête Idempotency-Key. Une requête HTTP POST n’est pas intrinsèquement idempotente, et la sécurité de sa répétition dépend du contrat réel du point de terminaison.[5] reAPI indique explicitement qu’il enregistre cet en-tête, mais ne l’utilise pas pour dédupliquer les générations. Répéter un POST accepté avec la même clé peut créer une autre tâche et un autre frais.[6]

Si les éléments restent peu concluants, lancer volontairement une tâche de remplacement peut tout de même relever d’une décision métier. Enregistre-la comme une autre tentative liée à l’opération initiale non résolue, en tenant compte du fait que les deux peuvent aboutir. Ne transforme pas silencieusement la première tentative en « non créée » simplement pour simplifier la file de nouvelles tentatives. Tu effacerais ainsi la trace nécessaire si un résultat ou un frais arrive tardivement.

Vérifie ce que n8n va répéter

La même ambiguïté passe facilement inaperçue dans un éditeur de workflow. Un nœud intitulé « Generate Video » peut soumettre le travail, puis attendre son résultat. Un nœud rouge peut indiquer que son délai d’attente est terminé alors que la prédiction distante continue.

La documentation officielle de l’intégration n8n de WaveSpeed décrit précisément ce comportement : le nœud de génération soumet une prédiction et attend son résultat. Un délai d’attente positif peut faire échouer le nœud alors que la prédiction continue. La documentation avertit que Retry On Fail de n8n relance le nœud entier et produit une nouvelle prédiction facturée séparément ; les échecs temporaires de polling font déjà l’objet de nouvelles tentatives en interne.[7] Cet avertissement concerne cette intégration, pas automatiquement chaque nœud communautaire.

Pour un workflow composé de nœuds HTTP Request, examine l’action du nœud configuré pour réessayer. n8n documente Retry on Fail comme un réglage au niveau du nœud.[8] Si ce nœud envoie le POST de génération, une nouvelle tentative renvoie ce POST. S’il ne fait que lire une tâche connue, c’est la lecture qui est répétée. Le texte d’erreur visible du workflow ne remplace pas l’examen du nœud.

Une conception utile consiste à conserver l’ID de tâche accepté entre la soumission et le polling. La reprise peut alors repartir de l’étape de lecture sans repasser par la création. Cela ne résout pas le cas de perte de la réponse de soumission décrit plus haut ; conserve séparément cette voie non résolue. Le redémarrage manuel d’une exécution entière mérite aussi cette vérification, car des étapes de création antérieures déjà réussies peuvent être rejouées.

Revenons au double clic hypothétique : remplacer le second clic par une nouvelle tentative automatique du nœud ne change pas le problème de facturation. L’application doit toujours savoir si elle interroge la tâche d’origine ou en demande une nouvelle.

Réessaie la lecture avec un point d’arrêt

Une défaillance temporaire lors de la lecture d’une tâche connue se prête davantage à une nouvelle tentative. Garde la même identité de tâche, respecte les règles documentées de polling et de limitation du débit de l’endpoint, puis arrête la boucle de répétition immédiate lorsque le nombre de tentatives autorisé ou le budget de temps écoulé est épuisé.

AWS décrit le backoff exponentiel plafonné, le jitter et des limites de tentatives pour éviter de surcharger une dépendance en difficulté.[1] Le jitter répartit dans le temps les prochaines tentatives des clients au lieu de les programmer toutes au même instant. Ces techniques gèrent la charge des nouvelles tentatives ; elles ne transforment pas un POST de création en opération dédupliquée.

Choisis une seule couche responsable de cette reprise. Si un SDK, un nœud de workflow et un worker externe répètent chacun indépendamment, le trafic obtenu peut dépasser ce que laisse penser le réglage externe. Examine les nouvelles tentatives déjà intégrées à l’intégration avant d’ajouter une autre boucle autour.

Quand le budget de lecture est épuisé, conserve l’ID de tâche pour un rapprochement ultérieur. Une échéance côté client indique combien de temps ce client a attendu. À moins qu’une opération d’annulation documentée ait réussi, elle ne prouve pas que la génération distante s’est arrêtée. Affiche un état de récupération non résolu au lieu de proposer un bouton « Réessayer » sans réserve qui soumettrait un nouveau travail.

Examine l’erreur précise avant de choisir un remplacement

Une fois l’erreur structurée obtenue, lis son code et le périmètre documenté. reAPI, par exemple, identifie 60001 et 60002 comme des échecs d’enregistrement d’une tâche ou de démarrage d’un workflow, avec remboursement des crédits.[4] Ces cas documentés appuient une décision de reprise différente de celle à prendre face à une réponse HTML 500 inconnue ou à une connexion perdue après la soumission. N’étends pas ce remboursement à toutes les erreurs serveur.

Si la réponse précise indique une entrée invalide ou un média inutilisable, corrige le problème signalé conformément à la documentation de cet endpoint avant de soumettre une autre tentative. Conserve les éléments de preuve de la tentative initiale et traite la soumission corrigée comme un nouveau travail ; modifier une entrée ne résout pas l’incertitude sur l’acceptation antérieure.

« Le serveur ne peut actuellement pas traiter cette requête » est tout aussi incomplet sans le statut HTTP et les détails de la réponse. Modifier plusieurs fois le prompt, actualiser le navigateur ou augmenter le délai d’attente ne permet pas de déterminer où l’échec côté serveur s’est produit. Pour un endpoint géré par un fournisseur, transmets la méthode, l’URL, l’heure UTC et les identifiants disponibles par son processus d’assistance ; le guide des erreurs de reAPI précise ces éléments.[4]

Un autre fournisseur peut être un remplacement utile si ses entrées, sorties et conditions de fonctionnement prises en charge correspondent à la tâche. Mais un autre nom d’hôte ne prouve pas à lui seul que le chemin d’échec est indépendant. Une réussite chez un autre fournisseur ne permet pas non plus de savoir ce qui est arrivé à la soumission initiale. Garde les deux tentatives visibles, y compris toute tâche initiale qui se termine plus tard.

Avant de reprendre un arriéré, fais le point sur le travail déjà envoyé. Les tâches connues doivent continuer à être observées ou avoir un résultat consigné ; les soumissions inconnues doivent avoir un responsable et une décision explicite quant à leur remplacement. La première nouvelle tentative réussie est utile, mais la reprise n’est compréhensible que si tu peux expliquer quels jobs distants peuvent exister pour chaque demande utilisateur.

Références

  1. AWS Builders Library: Timeouts, retries, and backoff with jitter. Conseils d’ingénierie publiés pour la première fois en 2019 ; effets de bord, nouvelles tentatives bornées et amplification des tentatives.
  2. MDN: HTTP 500 Internal Server Error. Définition et investigation côté serveur.
  3. reAPI Tasks. Polling, état, sortie et sémantique du règlement.
  4. reAPI Errors. Codes d’échec précis et éléments à fournir au support. Les décisions de nouvelle tentative ici tiennent aussi compte du contrat de soumission de la référence 6.
  5. MDN: Idempotent. Sémantique des méthodes HTTP et limites de l’hypothèse selon laquelle une répétition est sans risque.
  6. Présentation de l’API reAPI. Soumission de génération et contrat Idempotency-Key.
  7. Documentation officielle de l’intégration n8n de WaveSpeed. Délai d’attente du nœud, nouvelles tentatives du nœud entier et prédictions facturées séparément ; consultée le 15 novembre 2026.
  8. Documentation officielle n8n sur les problèmes courants de HTTP Request. Retry on Fail et paramètres de nouvelle tentative du nœud ; consultée le 15 novembre 2026.
Tous les guides