Surveillance des Flows et dépannage

Où surveiller les exécutions, comment lire une exécution échouée jusqu’au nœud en cause et les cinq pannes que vous rencontrerez vraiment : symptôme, cause et correction à votre portée.

Quoi surveiller#

• Suivi des exécutions (Integration → Runs) : toutes les exécutions dans une liste — flow et version, déclenchement (horaire / événement / manuel), statut (running, success, failed, retrying), durée et éléments traités. Filtrez par statut pour ne voir que les échecs.
• Détail d’exécution : cliquez sur une exécution pour la voir nœud par nœud — instantané d’entrée et de sortie de chaque étape et, pour l’étape en échec, le message d’erreur exact. Commencez toujours ici.
• Logs et lettres mortes (Integration → Logs) : les éléments en échec définitif arrivent dans la file des lettres mortes avec le flow, le nœud et l’erreur. Après correction de la cause, rejouez (replay) l’élément pour le retraiter, ou écartez-le s’il n’est plus voulu.
• Santé de la connexion : une exécution qui échoue dès le premier nœud avec une erreur d’auth est un problème de connexion, pas de flow ; le bouton Tester de la connexion le reproduit en quelques secondes.

Les cinq pannes ci-dessous couvrent presque tout ce que vous verrez. Pour chacune : à quoi elle ressemble, pourquoi elle arrive, et la correction — tout depuis l’interface.

1. Identifiants expirés ou invalides#

• Symptôme : les exécutions échouent dès le premier nœud avec 401 / échec d’auth ; le test de la connexion échoue pareil. Cela commence souvent d’un coup après des semaines de fonctionnement.
• Cause : l’autre plateforme a expiré ou roté l’identifiant — les tokens ont une durée de vie (ex. Wish : 30 jours ; certains tokens OAuth utilisateur : quelques heures) et les secrets changent quand quelqu’un les régénère.
• Correction : (1) obtenez un nouvel identifiant sur la plateforme (le répertoire indique où) ; (2) ouvrez la connexion, collez la nouvelle valeur, enregistrez ; (3) testez la connexion jusqu’à réussite ; (4) rejouez les lettres mortes produites pendant la panne.

2. Mapping manquant ou mauvais type#

• Symptôme : les exécutions échouent sur un nœud intermédiaire avec des erreurs comme « le champ X est requis », « SKU non mappé » ou une valeur rejetée pour mauvais type (du texte là où un nombre est attendu, une date au mauvais format). Les nouvelles commandes avec de nouveaux SKU sont le déclencheur classique.
• Cause : un champ source attendu par le mapping était vide ou absent sur ce document, les deux systèmes ne s’accordent pas sur le type d’un champ, ou un SKU du canal n’a jamais été associé à un produit OMS.
• Correction : (1) ouvrez l’exécution échouée et repérez le nœud et le champ en cause ; (2) SKU non mappés : associez-les dans la liste en attente de Product Mapping ; (3) champ manquant ou mauvais type : ouvrez le mapping du flow (ou de la connexion), mappez le bon champ source ou ajoutez une valeur par défaut / une conversion ; (4) lancez un dry run, publiez si vous avez modifié le flow, puis rejouez la lettre morte.

3. L’autre plateforme vous limite#

• Symptôme : les exécutions affichent « retrying » ou échouent avec 429 / « too many requests ». Les rafales aggravent la situation — après une grosse extraction manuelle ou à l’heure pile quand beaucoup de flows partent ensemble.
• Cause : chaque plateforme plafonne les appels API par minute/heure et par compte. Le connecteur réessaie déjà avec un délai — c’est le statut « retrying » — mais une rafale soutenue peut épuiser le quota.
• Correction : (1) pour un « retrying » occasionnel, ne faites rien — cela réussit généralement tout seul ; (2) si cela se répète, baissez la fréquence d’extraction sur la connexion / la planification du flow ; (3) décalez les horaires pour que plusieurs flows ne frappent pas la même plateforme à la même minute ; (4) évitez les extractions manuelles répétées pendant qu’un arriéré réessaie.

4. Échecs de webhook / rappel#

• Symptôme : les données qui devraient arriver en push n’arrivent jamais — numéros de suivi ou confirmations de fulfillment manquants, notifications de nouvelles commandes arrêtées — alors que l’extraction manuelle fonctionne. Les logs montrent des erreurs de livraison de webhooks.
• Cause : la plateforme émettrice n’a pas pu livrer à Docklify (problème réseau temporaire), l’abonnement a été perdu lors d’un changement d’identifiants, ou la connexion a été désactivée puis réactivée sans réenregistrer le rappel.
• Correction : (1) vérifiez dans Integration → Logs les erreurs de webhook et leurs heures — une courte rafale déjà terminée ne demande rien ; (2) testez la connexion : un test réussi revalide l’enregistrement du rappel sur la plupart des plateformes ; (3) si les pushes manquent toujours, désactivez puis réactivez la connexion pour forcer un nouvel abonnement ; (4) faites une extraction manuelle pour rattraper ce qui manque, puis surveillez l’arrivée du prochain événement réel.

5. Problèmes de format de données#

• Symptôme : des documents isolés échouent alors que d’autres de la même connexion passent — une commande rejetée pour adresse invalide, un téléphone au mauvais format, un code postal illisible ou un poids avec l’unité dans le nombre.
• Cause : la donnée elle-même, telle qu’elle existe sur la plateforme ou le document source, ne respecte pas les règles de format du destinataire. Le flow et les identifiants vont bien — c’est le document qui cloche.
• Correction : (1) ouvrez l’exécution échouée et lisez quel document et quel champ ont été rejetés — l’erreur les nomme ; (2) corrigez la donnée à la source quand c’est possible (l’adresse / le téléphone sur la commande ou la plateforme) ; (3) si la même particularité revient toujours de cette plateforme, traitez-la une fois dans le mapping : valeur par défaut, nettoyage ou conversion pour ce champ ; (4) rejouez la lettre morte du document corrigé.