Gestion des erreurs d'un flux d'intégration

Un flux d'intégration entre un CRM et un assistant IA va échouer : service indisponible, jeton périmé, donnée refusée. La question n'est pas d'éviter toute erreur, mais de décider à l'avance ce qui se passe ensuite. La méthode tient en six gestes : classer l'erreur, réessayer les erreurs temporaires avec une attente croissante, mettre de côté ce qui échoue pour de bon, rendre les actions rejouables sans effet double (idempotence), alerter une personne, et rattraper ce qui a été perdu. Les règles chiffrées ci-dessous viennent des documentations de Pipedrive et de n8n, lues le 15/11/2026.

1. Classer : temporaire ou définitive

La règle d'or : ne jamais réessayer une erreur définitive en boucle. Les limites d'appels propres à Pipedrive sont décrites dans l'intégration API Pipedrive. Dans le doute, traitez l'erreur comme temporaire pour quelques essais, puis comme définitive.

2. Réessayer avec une attente croissante

Réessayer tout de suite, c'est souvent frapper un service déjà en difficulté. On espace les essais en allongeant l'attente à chaque fois (1 minute, 5 minutes, 30 minutes…) et on borne le nombre d'essais. Un exemple vu dans la documentation : Pipedrive réessaie un webhook non reçu trois fois, après 3, 30 et 150 secondes, soit des écarts qui s'allongent. Les valeurs de votre propre flux sont à choisir selon la tolérance du métier ; elles ne sortent d'aucune norme. Ajoutez un peu d'aléa aux délais quand plusieurs tâches échouent en même temps, pour qu'elles ne repartent pas toutes à la même seconde.

3. Une file des échecs

Quand les essais sont épuisés, ne jetez pas le message : rangez-le dans une file des échecs (une table, une file de messages, un classeur selon la taille du projet) avec :

• le contenu d'origine, tel qu'il est arrivé ;
• l'erreur reçue et l'heure de chaque essai ;
• l'identifiant de l'événement et celui de l'enregistrement concerné ;
• un état : à examiner, rejoué, abandonné.

Une personne doit pouvoir lire cette file, corriger la cause, puis relancer. Sans file, chaque panne devient un cas particulier à reconstituer.

4. Idempotence : rejouer sans effet double

Réessayer et rejouer exposent à un risque : faire deux fois la même chose (deux rappels créés, deux messages envoyés). Une action idempotente donne le même résultat qu'on l'exécute une fois ou dix. Pratiques courantes :

• stocker les identifiants d'événements déjà traités et ignorer un doublon ;
• avant de créer, chercher si l'enregistrement existe déjà (clé naturelle : référence de commande, adresse de messagerie) ;
• préférer « mettre à jour avec cette valeur » à « ajouter 1 ».

Attention à un point que la documentation de Pipedrive ne tranche pas : la page lue sur les webhooks v2 décrit meta.id, l'identifiant de l'événement, mais ne décrit aucun mécanisme d'idempotence et ne dit pas si les nouvelles tentatives gardent le même meta.id. Testez-le sur votre compte avant de bâtir votre déduplication sur ce champ. Elle indique en revanche un champ attempt : 1 pour l'envoi initial, puis 2, 3 et 4 pour les trois nouvelles tentatives, ce qui permet au moins de savoir qu'une livraison est un renvoi.

5. Alerter : qui, quand, avec quoi

Une erreur sans destinataire n'est qu'une ligne de journal. Décidez qui est prévenu, par quel canal et à partir de quel seuil (une erreur définitive tout de suite, une erreur temporaire seulement après le dernier essai). Dans n8n, le mécanisme est documenté :

• un workflow d'erreur commence par le nœud Error Trigger ; on le choisit dans les paramètres du workflow surveillé (champ « Error workflow ») ;
• il reçoit l'identifiant et l'adresse de l'exécution, le message et la pile d'erreur, le dernier nœud exécuté, le mode, l'identifiant et le nom du workflow ;
• un même workflow d'erreur peut servir plusieurs workflows, et envoyer par exemple un message par courriel ou Slack ;
• le nœud Stop And Error fait échouer volontairement une exécution, ce qui déclenche ce workflow : utile pour traiter une réponse « 200 mais données vides » comme une erreur ;
• limites : le workflow doit être publié, il ne se teste pas en exécution manuelle, et l'identifiant et l'adresse d'exécution demandent que l'exécution soit enregistrée en base. Si l'erreur vient du déclencheur lui-même, la structure des données change (objet trigger).

Le message d'alerte doit contenir de quoi agir : quel flux, quel client, quel enregistrement, quelle erreur, et le lien vers l'exécution. Le suivi dans la durée est traité dans la maintenance d'un assistant IA.

6. Rattraper les événements perdus (webhooks)

Un webhook est une notification que le CRM envoie à votre serveur. Si votre serveur ne répond pas, elle peut ne jamais arriver. Les règles de Pipedrive (webhooks v2) montrent pourquoi il faut un filet :

• la livraison est réussie si votre serveur répond par un code 2XX ; tout autre code, ou plus de 10 secondes, est un échec ;
• après un échec : trois nouvelles tentatives, à 3, 30 et 150 secondes ;
• le compteur de suspension monte seulement quand la première tentative échoue ; à 10, le webhook est suspendu 30 minutes, puis réactivé ;
• pendant la suspension, le message est perdu : rien n'est conservé pour un nouvel essai ;
• sans aucune livraison réussie pendant 3 jours consécutifs, le webhook est supprimé.

Conséquence pratique : une panne de quelques heures perd des événements, une panne de 3 jours supprime le webhook. Prévoyez donc :

1. de répondre vite (2XX) et de traiter en arrière-plan, pour ne pas dépasser 10 secondes ;
2. de noter l'heure de la dernière livraison réussie ;
3. un rattrapage après toute alerte ou tout redémarrage : relire par l'API les enregistrements modifiés depuis cette heure, puis les traiter comme s'ils étaient arrivés par webhook (d'où l'intérêt de l'idempotence) ;
4. un passage régulier de contrôle (par exemple une fois par nuit) qui compare les deux sources, pour rattraper les pertes que personne n'a vues ;
5. une vérification que les webhooks existent encore, avec recréation si besoin.

Chaque éditeur a ses propres règles, parfois différentes : lisez celles de votre CRM avant de dimensionner le rattrapage. Le coût des relectures en appels est à mettre en regard du budget autorisé.

Checklist de recette

• Chaque erreur possible est classée : temporaire ou définitive.
• Les essais sont bornés et espacés.
• La file des échecs existe, et quelqu'un sait la lire.
• Rejouer un message deux fois ne crée pas de doublon.
• Une panne simulée déclenche une alerte reçue par la bonne personne.
• Un rattrapage après arrêt du serveur a été testé de bout en bout, dans un environnement de test (voir tester dans un sandbox CRM).
• Pour n8n : le workflow d'erreur a été vérifié sur une vraie erreur d'exécution automatique, pas en test manuel ; pour un projet avec n8n, voir le guide n8n.