Gérez les erreurs, les retries et les cas limites

Anticipez les erreurs inévitables d'un workflow en production

Imaginez : à 3h du matin, un incident est détecté par le monitoring, le webhook se déclenche ; et le ticket disparaît dans le vide. HubSpot était en maintenance. Sans gestion d'erreurs, le workflow s'est arrêté.

C'est le scénario le plus courant : un workflow qui marche en test casse en production pour des raisons non anticipées.

Voici les causes les plus fréquentes :

• un service externe ne répond pas (API HubSpot en maintenance, timeout réseau) ;

• une limite de requêtes atteinte (rate limit) ; vous avez envoyé trop d'appels en trop peu de temps ;

• un champ qui a changé de nom dans la réponse d'une API après une mise à jour ;

• une donnée inattendue qui fait planter une expression (nulllà où vous attendiez un texte).

L'enjeu n'est pas d'éviter toutes les pannes, c'est impossible. C'est de les détecter rapidement et de continuer à traiter les tickets malgré elles.

Découvrez les options de gestion des erreurs

Il existe deux façons de gérer les erreurs dans n8n, avec des usages bien distincts.

Option 1 — La gestion in-workflow : vous anticipez les échecs directement dans le flux du workflow. Vous créez une branche alternative qui s'active quand un nœud échoue. C'est utile pour des cas spécifiques et prévisibles : « si HubSpot ne répond pas, continuer sans enrichissement ».

Option 2 — L'Error Workflow dédié : un workflow de secours que vous branchez sur plusieurs workflows à la fois. Dès qu'un de vos workflows plante, n8n l'appelle automatiquement. C'est le mécanisme idéal pour centraliser vos alertes et votre supervision.

Les deux approches sont complémentaires, le plus souvent, vous ferez les deux :

1. Utiliser in-workflow quand l'erreur a un impact fonctionnel prévisible (ex. HubSpot absent → continuer sans enrichissement).

2. Utiliser un Error Workflow pour la supervision : alerter, consigner l'incident, déclencher une récupération.

Option 1 — Implémentez des branches succès/échec avec continueOnFail

Par défaut, quand un nœud échoue, n8n arrête l'exécution et marque le workflow en erreur. Pour changer ce comportement, activez l'optioncontinueOnFailsur le nœud concerné (Settings → On Error → Continue).

Quand cette option est activée, le nœud transmet les données sur deux sorties :

1. Succès (chemin vert) : l'appel s'est bien passé, le ticket est enrichi ;

2. Erreur (chemin rouge) : le nœud a échoué, les détails de l'erreur sont disponibles dans$json.

Dans le pipeline de notre scénario, vous obtenez deux branches sur le nœud HubSpot :

1. Chemin succès → ticket enrichi avecout_client_name,out_client_plan, etc.

2. Chemin erreur → ticket continue sans enrichissement, avec tous les champsout_client_*ànull.

Option 2 — Construisez un Error Workflow réutilisable

Pour le configurer :

1. Créez un nouveau workflow avec un nœud Error Trigger.

2. Ajoutez vos actions de supervision (alerte Slack, log dans un Google Sheet, etc.).

3. Dans votre pipeline principal (Settings → Error Workflow), sélectionnez ce workflow.

Le nœud Error Trigger expose des variables comme$execution.workflowNameou$json.error.message. Utilisez-les pour construire un message d'alerte actionnable. Soyez précis, ne vous contentez pas de :

« Une erreur s'est produite »

Privilégiez un message du type :

« Le workflow Pipeline tickets a échoué à l'étape Enrichir via HubSpot pour le ticket INC-2024-001 ».

C'est une limite réelle : si Slack est aussi indisponible, l'alerte ne part pas. Gardez votre Error Workflow simple, sans dépendances vers des services tiers non critiques.

Appliquez la bonne stratégie de retry selon le type d'erreur

Toutes les erreurs ne méritent pas la même réponse. Avant de configurer un retry, posez-vous la question : est-ce que relancer l'appel a des chances de fonctionner ?

Dans n8n, configurez le retry via Settings → Retry on Fail sur le nœud concerné. Vous définissez le nombre de tentatives et l'intervalle d'attente. Pour les erreurs4xx, ne configurez pas de retry : relancer une requête avec un token invalide consomme inutilement vos quotas d'API, et ne changera jamais rien.

À vous de jouer !

Revenons à notre projet de workflow pour AgroTech !

Consigne

Le pipeline que vous avez construit jusqu'ici s'arrête net dès que l'API HubSpot rencontre un problème ou ne répond pas. Votre mission : rendre le flux résilient.

Ajoutez une stratégie de gestion d'erreur au nœud qui interroge HubSpot :

1. Si HubSpot répond, le relevé agricole est enrichi normalement avec les données de l'exploitation.

2. Si HubSpot ne répond pas(simulez la panne en modifiant temporairement la clé API ou l'URL), le relevé continue son cheminement sans enrichissement : tous les champs  out_farm_*  valent null.

3. Une alerte est envoyée (Slack, Discord ou Email) contenant : le nom du workflow, la date/heure de l'incident, l'identifiant du capteur/exploitant (  out_device_email  ), et le type d'erreur HTTP.

• Le workflow ne s'arrête jamais brutalement à cause d'une panne HubSpot.

• En cas d'échec d'enrichissement,  out_farm_owner  ,  out_farm_name  ,  out_farm_crop_type  et  out_farm_registered_since  valent null.

• L'alerte indique clairement si l'erreur est un  4xx  (problème de configuration/clé chez vous) ou un  5xx  / Timeout (panne des serveurs HubSpot), car le niveau d'urgence n'est pas le même.

Corrigé

Voici un exemple de ce que vous pouviez faire pour y arriver :

Capture d’écran du workflow n8n intitulé 'Résilience & Erreur HubSpot AgroTech' dans l’éditeur.

• Objectif : Gérer l’indisponibilité de l’API HubSpot lors de la recherche d’une exploitation.

• Comportement :

  • Succès : Enrichissement avec les champsout_farm_*.

  • Erreur :

    1. Mode dégradé :out_farm_*forcés ànull.

    2. Alerte structure : catégorisation 4xx vs 5xx/timeouts.

    3. Simulation d’envoi Slack/Discord.

• Test : Le nœud HTTP utiliseAuthorization: Bearer INVALID_POUR_TESTpour forcer une erreur 401 et valider la résilience.

• Structure du workflow (sur fond rouge) :

  • Nœud 1 : 'When clicking Test workflow' (déclencheur).

  • Nœud 2 : 'Simuler relevé normalisé' (données de test).

  • Nœud 3 : 'Rechercher Exploitation HubSpot' (POST vers l’API HubSpot).

  • Nœud 4 : 'Fallback Sans Enrichissement' (gestion des erreurs).

  • Nœud 5 : 'Enrichir Relevé (Succès)' (ajout des champsout_farm_*).

  • Nœud 6 : 'Formatter Alerte Erreur' (préparation du message d’erreur).

  • Nœud 7 : 'Envoyer Alerte Slack/Discord' (envoi de l’alerte).

• Logs (en bas) : Exécution réussie en 652ms pour tous les nœuds.

• Bouton 'Execute workflow' en orange.

Capture d’écran des paramètres et de l’exécution du nœud 'Rechercher Exploitation HubSpot' dans n8n.

• Input : Données provenant de 'Simuler relevé normalisé' avec :

  • out_source: Station Météo Web

  • out_subject: Risque de Gel

  • out_message: Chute de température brutale sous 0°C

  • out_device_email: emailmaria@hubspot.com

  • out_priority: high

  • out_created_at: 2026-03-15T06:06:00.002Z.

• Paramètres :

  • Method : POST.

  • URL :https://api.hubspot.com/crm/v3/objects/contacts/search.

  • Authentication : Aucune (pour simuler une erreur).

  • Headers :

    • Authorization: Bearer INVALID_POUR_TEST(forcé pour générer une erreur 401).

    • Content-Type: application/json.

• Output :

  • Error Branch (1 item) :

    • message: 401 - {"status":"error","message":"Authentication credentials not found..."}

    • name: AxiosError

    • code: ERR_BAD_REQUEST

    • status: 401.

Capture d’écran du nœud 'Rechercher Exploitation HubSpot' avec une authentification valide.

• Input : Même structure que le screenshot précédent (ex:out_source: Station Météo Web).

• Paramètres :

  • Method : POST.

  • URL :https://api.hubspot.com/crm/v3/objects/contacts/search.

  • Authentication :

    • Generic Credential Type → Bearer Auth →n8n-test-api-hubspot.

  • Headers :

    • Authorization: Bearer INVALID_POUR_TEST(remplacé par le token valide en exécution réelle).

    • Content-Type: application/json.

• Output :

  • Success Branch (1 item) :

    • total: 1

    • results[0]:

      • id: 811076535496

      • properties:

        • firstname: Maria

        • lastname: Johnson (Sample Contact)

        • email: emailmaria@hubspot.com

        • createdate: 2026-06-30T14:57:51.665Z

        • hs_object_id: 811076535496

        • archived: false.

Capture d’écran du workflow 'Résilience & Erreur HubSpot AgroTech' après exécution réussie.

• Logs (en bas à gauche) :

  • Success in 191mspour l’ensemble du workflow.

  • Rechercher Exploitation HubSpot: Success in 23ms.

• Output du nœud 'Enrichir Relevé (Succès)' :

  • total: 1

  • results[0].properties:

    • id: 811076535496

    • out_farm_owner: Maria Johnson (Sample Contact)

    • out_farm_name: null

    • out_farm_crop_type: Viticulture Standard

    • out_farm_registered_since: 2026-06-30T14:57:51.665Z.

• Bouton : 'Node executed successfully' en vert.

Capture d’écran des paramètres du nœud 'Enrichir Relevé (Succès)' dans n8n.

• Input : Données de la Success Branch de 'Rechercher Exploitation HubSpot' avec :

  • total: 1

  • results[0].properties:createdate,email,firstname,hs_object_id,lastname, etc.

• Paramètres (mode Manual Mapping) :

  • Fields to Set :

    • out_farm_owner:= {{ $json.results[0].properties.firstname + ' ' + ($json.results[0].properties.lastname || '') }}→Maria Johnson (Sample Contact).

    • out_farm_name:= {{ $json.results[0].properties.company || null }}→null.

    • out_farm_crop_type:= {{ $json.results[0].properties.jobtitle || 'Viticulture Standard' }}→Viticulture Standard.

    • out_farm_registered_since:= {{ $json.results[0].properties.createdate }}→2026-06-30T14:57:51.665Z.

• Output : Données enrichies avec les champsout_farm_*(ex:out_farm_owner: Maria Johnson).

Capture d’écran des paramètres du nœud 'Fallback Sans Enrichissement' dans n8n.

• Input : Données de la Error Branch de 'Rechercher Exploitation HubSpot' avec :

  • out_source: Station Météo Web

  • out_subject: Risque de Gel

  • out_message: Chute de température brutale sous 0°C

  • error:

    • message: 401 - Authentication credentials not found...

    • status: 401.

• Paramètres (mode Manual Mapping) :

  • Fields to Set (tous forcés ànullpour le mode dégradé) :

    • out_farm_owner: null

    • out_farm_name: null

    • out_farm_crop_type: null

    • out_farm_registered_since: null.

  • Include Other Input Fields : Activé (conserve les champsout_*initiaux eterror).

• Output :

  • Champsout_farm_*ànull.

  • Champs initiaux (out_source,out_subject, etc.) eterrorconservés.

• Bouton : 'Workflow executed successfully' en vert.

Capture d’écran des paramètres du nœud 'Envoyer Alerte Slack/Discord' dans n8n.

• Input : Données de 'Formatter Alerte Erreur' avec :

  • workflow_name: Corrigé 4 - Résilience HubSpot AgroTech

  • timestamp: 2026-07-28T09:58:34.288Z

  • device_email: emailmaria@hubspot.com

  • status_code: 401

  • error_category: [4xx] Erreur de Configuration / Auth

  • error_message: 401 - Authentication credentials not found...

  • slack_message: *Alerte Pipeline Agrotech* *Workflow: Corrigé 4 - Résilience...*.

• Paramètres (mode Manual Mapping) :

  • Fields to Set :

    • notification_payload:= {{ $json.slack_message }}→ Message formaté pour Slack/Discord.

    • sent_at:= {{ new Date().toISOString() }}→2026-07-28T09:58:49.75Z.

    • channel:#alerts-agrotech.

• Output :

  • notification_payload: *Alerte Pipeline Agrotech* *Workflow: Corrigé 4...*

  • sent_at: 2026-07-28T09:58:49.75Z

  • channel: #alerts-agrotech.

En résumé

• Un workflow en production tombe pour des raisons prévisibles : service indisponible, rate limit, champ manquant. Anticipez ; ne découvrez pas le problème le lendemain matin.

• continueOnFailcrée deux chemins : succès et erreur. Le ticket n'est jamais perdu à cause d'un service tiers.

• Un Error Workflow dédié centralise la supervision sur plusieurs workflows à la fois ; un seul endroit pour vos alertes.

• Avant de configurer un retry, vérifiez si relancer a des chances de fonctionner. Les erreurs4xxne se résolvent pas en réessayant.

Dans le prochain chapitre, vous allez protéger le pipeline contre un autre scénario réel : 50 clients signalent le même bug en 5 minutes. Vous allez apprendre à regrouper les tickets et à rendre le pipeline “idempotent”.