Erreurs et rejeu

Un workflow dialogue avec des systèmes qui échouent parfois : un fournisseur de messagerie qui ne répond pas à temps, un modèle d’IA qui limite son débit, une API tierce qui refuse une requête. Mankomail exécute chaque workflow étape par étape et enregistre le résultat de chaque étape : un échec s’arrête à l’étape où il s’est produit et ne fait jamais perdre en silence ce qui précède.

Cette page suit un échec du début à la fin : ce que l’étape fait d’elle-même, ce que vous réglez par nœud, ce qu’il advient de l’exécution, comment vous êtes prévenu, et comment la rejouer une fois corrigée. Pour les statuts d’une exécution, voyez Exécutions.

Échecs passagers et échecs définitifs

Chaque échec d’une étape relève de l’une de deux familles, et c’est elle qui décide de la suite.

• Passager : un échec qui peut réussir si l’on réessaie plus tard — une erreur réseau, un fournisseur brièvement indisponible, une tentative qui a dépassé son délai. L’étape est retentée, après un délai.
• Définitif : un échec qu’une nouvelle tentative ne corrigerait pas — un paramètre invalide, une connexion absente ou révoquée, une adresse bloquée par la garde réseau, une réponse trop lourde. L’étape n’est pas retentée.

Un échec de nature inconnue est traité comme passager : retenter quelques fois coûte moins cher qu’abandonner une étape à cause d’une erreur réseau passagère.

Une limite de débit d’un fournisseur n’est pas un échec : l’étape est reportée à l’heure que le fournisseur indique (Retry-After), sans consommer de tentative.

Les nouvelles tentatives, à trois niveaux

Le nombre de tentatives d’une étape, et l’attente entre deux, viennent du premier de ces trois niveaux qui les fixe :

Niveau	Où	Défaut
Le nœud	l’onglet Réglages du nœud, section Nouvelles tentatives	—
Le type de nœud	le catalogue	nœuds d’IA : 3 tentatives, 10 s, 5 min par tentative
Mankomail	intégré	3 tentatives, 5 s, 2 min par tentative

Dans l’onglet Réglages du nœud, la section Nouvelles tentatives affiche le défaut qui s’applique (« Défaut pour ce type de nœud : … » ou « Défaut : … »). Régler pour ce nœud ouvre deux champs :

• Nombre de tentatives : première tentative comprise, donc 1 veut dire aucune nouvelle tentative. Entre 1 et 10.
• Délai avant la première nouvelle tentative : entre 1 seconde et 1 heure. Les délais suivants doublent, jusqu’à 15 minutes, avec un peu d’aléa pour que de nombreuses exécutions ne retentent pas au même instant.

Une phrase sous les champs dit ce qui se passera, par exemple « Si l’étape échoue : nouvelle tentative après 5 s, 10 s, puis abandon. » Pendant un essai, chaque délai est ramené à 2 secondes : un essai dans l’éditeur n’attend pas qu’un fournisseur se calme.

Seuls les échecs passagers sont retentés. Un échec définitif termine l’étape dès sa première tentative.

Le délai d’une tentative

La section Délai maximum du même onglet règle Délai maximum d’une tentative, entre 5 secondes et 30 minutes. Une tentative qui le dépasse est réellement interrompue, même si le nœud ne s’arrête pas de lui-même, et l’étape échoue avec le code node_timeout. Une tentative interrompue compte comme un échec passager : « pas fini à temps » n’est pas « ne finira jamais ».

Si l’échec persiste

Quand une étape a épuisé ses tentatives, ou échoue de façon définitive, la section Si l’échec persiste décide de la suite. Trois choix :

Choix	Ce qui se passe
Arrêter l’exécution	L’exécution s’arrête en échec. Elle apparaît dans Activité › À traiter et lance le workflow d’erreur, s’il y en a un.
Continuer sans cette étape	Les nœuds suivants s’exécutent quand même, sans données de cette étape : le chemin de sa sortie reste vide.
Suivre la sortie Erreur	Une sortie Erreur apparaît sur le nœud : reliez-la aux étapes à lancer en cas d’échec (prévenir quelqu’un, mettre le mail de côté).

Les nouvelles tentatives passent toujours avant ce choix : un nœud réglé pour continuer ou suivre la sortie Erreur est d’abord retenté, et seul un échec définitif prend ce chemin. Une étape rattrapée par Continuer ou par la sortie Erreur compte comme réussie : l’exécution poursuit, et n’est pas une exécution en échec.

Les effets incertains

Certains nœuds agissent chez un service tiers : Requête HTTP, les notifications, et les nœuds des intégrations (Airtable, Notion, Google, Microsoft, Yousign, MyNotary…). Si une tentative d’un tel nœud est coupée en plein appel — son délai est passé, ou le serveur a redémarré —, on ne peut pas savoir si le service a reçu la requête.

Mankomail ne la retente pas à l’aveugle. L’étape échoue avec le code step_effect_uncertain, qui est un échec définitif : le choix Si l’échec persiste s’applique, et c’est vous qui tranchez. Vérifiez chez le service si l’action a eu lieu ; si elle n’a pas eu lieu, reprenez l’exécution depuis cette étape (voir Rejouer une exécution). L’onglet Réglages de ces nœuds le dit dans une note.

Les autres nœuds sont retentés sans risque après une interruption :

• les nœuds sans effet extérieur (IA, conditions, transformations, appels de sous-workflow, contrôle de flux) : rien n’a pu se produire hors de Mankomail ;
• l’envoi, le déplacement ou le suivi d’un mail, l’écriture dans une Table, l’émission d’un signal : Mankomail enregistre ces effets sous une clé qui ne change pas d’une tentative à l’autre, si bien qu’un effet déjà passé est reconnu, pas répété.

Ce que dit l’erreur d’une exécution

Une étape en échec montre son erreur dans l’exécution, sur le canvas et dans le détail du nœud. Le détail donne :

Champ	Contenu
Code	Un code stable, traduit à l’écran (node_timeout, step_effect_uncertain, http_blocked, mail.mailbox_required…). Voir Codes d’erreur.
Message du serveur	Le détail technique, à coller dans un ticket. Jamais un secret.
Nœud et Type de nœud	L’étape qui a échoué.
Nature	Échec définitif, ou Échec passager, tentatives épuisées.
Tentative	Par exemple « tentative 3/3 ».
Tentatives précédentes	Chaque tentative échouée avant la dernière, avec son erreur, et interrompue quand elle a été coupée.
Version exécutée et Horodatage	Quelle version du workflow a tourné, et quand.

L’étape garde aussi les paramètres qu’elle a réellement reçus, expressions résolues et secrets masqués : vous voyez ce qu’on a donné au nœud sans le rejouer. Tant qu’une étape attend sa prochaine tentative, elle reste En cours et affiche Nouvelle tentative programmée.

Copier le détail de l’erreur copie tout cela. Le détail peut contenir une adresse ou un objet de mail : relisez-le avant de le partager.

Le workflow d’erreur

Un workflow peut désigner un autre workflow qui démarre quand l’une de ses exécutions réelles échoue. Réglez-le dans l’onglet Réglages du workflow, section En cas d’échec, champ Workflow d’erreur (« Aucun » par défaut). Le workflow choisi doit être l’un des vôtres, différent de celui-ci, et commencer par le déclencheur Échec d’un workflow. Il n’a pas besoin d’être publié pour être choisi, mais il doit l’être, et ne pas être en pause, pour démarrer.

Le workflow d’erreur reçoit :

• le même mail porteur que l’exécution échouée, quand il y en avait un : {{ email.… }} fonctionne, et vous pouvez répondre dans le fil ou déplacer le mail ;
• un compte rendu sous data.failure : workflowId, workflowName, executionId, workflowVersionId, failedAt, error (code, message, kind, attempts), nodeId, nodeName, nodeType, mailboxId, messageId.

Il ne démarre jamais pour un essai, pour une itération de boucle (c’est la boucle qui échoue, une fois, dans son exécution parente), pour une exécution elle-même lancée par un workflow d’erreur (pas de cascade d’alertes), ni pour lui-même. L’échec est toujours consigné dans Activité › À traiter, workflow d’erreur ou non : le workflow d’erreur est un confort de plus, pas le canal d’alerte.

Où apparaissent les échecs

• Activité › À traiter liste les échecs que vous n’avez pas encore vus, avec les approbations qui vous attendent. Chaque carte nomme le workflow, l’étape en échec (« Étape « Trier les devis » ») et un court résumé de l’erreur, avec Ouvrir l’exécution, Rejouer et Marquer comme vu. Marquer comme vu ne répare rien et n’efface rien : l’exécution reste en échec, elle sort seulement du bandeau.
• L’onglet Exécutions de l’éditeur liste les exécutions du workflow. Filtrez-les par statut, par nature (Essais, Réelles) et avec Chercher un mail, qui cherche dans l’objet et l’expéditeur du mail déclencheur. Ouvrez une exécution pour la voir sur le canvas.
• Le tableau de bord d’accueil montre les échecs récents et les workflows qui échouent le plus.

Rejouer une exécution

Rejouer relance une exécution en échec ou annulée, pour de vrai, avec les mêmes données de déclenchement : le même mail, le même corps de webhook. Un essai ne se rejoue jamais : il se relance depuis l’éditeur. La confirmation pose deux questions.

D’où repartir

Choix	Ce qui tourne	Effets
Depuis le début (défaut)	tout le workflow	chaque effet réel déjà produit repart : un mail déjà parti est renvoyé
Depuis l’étape en échec	seulement ce qui n’avait pas abouti ; les étapes réussies sont gardées telles quelles	aucun effet déjà produit ne repart

Sur quelle version

Choix	Quel graphe
La version publiée (défaut)	celle qui porte vos corrections : le choix habituel après avoir réparé
La version d’origine	celle qui a tourné, pour reproduire l’échec

Avant de confirmer, la fenêtre liste les effets réels déjà produits par cette exécution et, pour chacun, s’il repartira ou ne repartira pas. Quand l’étape en échec est ouverte sur le canvas, Reprendre depuis cette étape est le même rejeu, lancé depuis l’étape en échec.

Depuis l’étape en échec, les étapes sont gardées par nœud : sur la version publiée, un nœud qui existe toujours garde sa sortie d’origine même si vous avez changé ses paramètres ; un nœud nouveau tourne. Une étape rattrapée par Continuer ou par la sortie Erreur dans l’exécution d’origine compte comme réussie et est gardée ; pour la relancer, rejouez depuis le début.

Un rejeu est refusé quand le workflow est archivé, quand la boîte de l’exécution d’origine est déconnectée ou retirée, quand l’exécution est encore en cours ou a réussi, quand la version demandée n’est pas disponible (aucune version publiée, ou version d’origine supprimée), et quand l’expéditeur du mail est désormais exclu de votre périmètre. La nouvelle exécution est reliée à l’origine : elle porte Rejeu, avec Ouvrir l’exécution d’origine.

Rejouer tous les échecs

Après une correction, Rejouer tous les échecs, dans l’onglet Exécutions, rejoue d’un coup les exécutions réelles en échec du workflow pas encore rejouées, les plus anciennes d’abord, sur 24 heures, 7 jours ou 30 jours, avec les deux mêmes choix. Celles qui ne peuvent pas être rejouées sont laissées de côté et comptées. Les essais ne sont jamais concernés.

Annuler une exécution

Annuler l’exécution arrête une exécution en file, en cours ou en attente : plus aucune étape ne démarre, ses attentes sont fermées, et les exécutions qu’elle a lancées (sous-workflows, itérations de boucle) sont annulées aussi. Les étapes déjà faites ne sont pas défaites : un mail déjà parti reste parti, et une étape en train d’appeler un service peut encore aboutir. Laisser tourner ferme la fenêtre sans rien annuler.

Mettre hors ligne, archiver ou mettre en pause un workflow n’annule pas ses exécutions en cours.

Par l’API, POST /api/v1/workflows/{id}/executions/cancel annule toutes les exécutions en cours d’un workflow (200 au plus par appel ; rappelez tant que hasMore vaut true), et POST /api/v1/executions/cancel annule une liste d’exécutions.

Les limites d’un workflow

La section Exécution de l’onglet Réglages du workflow porte deux limites. Elles s’appliquent tout de suite, sans republier.

Exécutions simultanées. Combien d’exécutions réelles de ce workflow tournent en même temps. Les suivantes attendent leur tour, En file, dans l’ordre d’arrivée : rien n’est perdu. Les essais, les exécutions lancées par un autre workflow, les itérations de boucle et les exécutions en attente (d’une approbation, d’un délai ou d’un signal) ne comptent pas. Champ vide : le défaut de l’instance (WORKFLOW_MAX_CONCURRENCY, 10). L’instance plafonne aussi l’ensemble des workflows (EXECUTIONS_MAX_CONCURRENT, 100).

Durée maximale d’une exécution. Seul le temps de travail compte : une attente d’approbation, de délai ou de signal ne consomme rien. Au-delà, l’exécution est arrêtée et passe en échec avec le code execution_timeout, avec un écart de deux minutes au plus ; les étapes encore en cours sont fermées, et le workflow d’erreur démarre s’il y en a un. Au moins une minute. Champ vide : le défaut de l’instance (EXECUTION_TIMEOUT_MS, une heure), plafonné par EXECUTION_TIMEOUT_MAX_MS (24 heures). Une étape en train d’appeler un service à ce moment n’est pas interrompue. Voir Variables d’environnement.

Ce qui se produit au plus une fois

Effet	Dans une exécution (tentatives, redémarrages)	Rejeu depuis le début	Rejeu depuis l’étape en échec
Mail : envoi, brouillon, déplacement, suivi	au plus une fois	refait	pas refait
Écriture dans une Table	au plus une fois	refaite	pas refaite
Signal	au plus une fois	refait	pas refait
Appel d’un modèle d’IA	répété sans conséquence, sauf son coût	refait	pas refait
HTTP, notification, intégrations	au moins une fois quand le nœud rapporte son échec ; au plus une fois après une interruption (step_effect_uncertain)	refait	pas refait
Sous-workflow, itération de boucle	lancé une fois	relancé	pas relancé si l’étape appelante avait réussi