SYS_PRO_5 — Gestion des erreurs et résilience

Manuel LÉGER. Processus implémenté (Lot 5 error_handler ; branche llm_error Lots 6g/6h). Source du quoi : 07_Reference_Systeme.md §B2.8 (error_handler) + §B2.11 (branche d'échec agent_call). Source du pourquoi : ADR-029 (D5), ADR-034. [CORPUS]

Objet et finalité

Garantir qu'une erreur — exception non gérée d'un workflow ou échec d'appel LLM — soit capturée, signalée et isolée sans casser le reste du système. Deux mécanismes complémentaires : (a) capture générique des exceptions (error_handler via Error Workflow natif) ; (b) gestion dédiée de l'échec LLM dans agent_call (trace + notif llm_error + sortie propre {success:false} sans throw). [CORPUS]

Principes transverses : l'observabilité ne casse jamais le flux ni elle-même (fire-and-forget, anti-récursion) ; un échec attendu (LLM) rend un contrat de service, il ne lève pas d'exception. [CORPUS]

Pilote

Direction pilote : SYS — Système.
Acteurs : error_handler (Error Workflow natif) ; la branche d'échec de agent_call. Pas d'agent LLM. Supervision : gérant (lit system-errors). [CORPUS]

Déclencheurs (entrées)

Exception non gérée dans un workflow critique → déclenche error_handler (Error Trigger natif), uniquement en exécution production/integrated (jamais en run manuel éditeur — P-6g-2). [CORPUS]
Échec LLM dans agent_call : HTTP non-2xx ou soft-error D2 (HTTP 200 + body.error / choices vide). [CORPUS]

Sorties et livrables

error_handler : notif workflow_error (canal system-errors) avec contexte (workflow, nœud, execution_id, message). [CORPUS]
Branche llm_error d'agent_call : 1 ligne télémétrie success=false + 1 notif llm_error + sortie { success:false, content:null, error }. [CORPUS]
Garantie : sur échec LLM, une seule notif (llm_error), zéro doublon workflow_error (pas de throw → error_handler ne fire pas). [CORPUS]

Acteurs

Acteur	Rôle
`error_handler`	capture centralisée des exceptions → `notify_system` (`workflow_error`) [CORPUS]
Branche d'échec `agent_call`	`Build error log payload` → `log_llm_call(success=false)` → `notify_system(llm_error)` → `Error output` [CORPUS]
`notify_system`	véhicule les deux notifs (cf. `SYS_PRO_4`) [CORPUS]
Gérant	lit `system-errors`, agit

Logigramme (étapes macro)

A) Exception non gérée (prod/integrated)
   workflow critique → throw → Error Trigger → error_handler
      → contexte (workflow,node,execution_id,message) → notify_system(workflow_error) → system-errors

B) Échec LLM dans agent_call (6h)
   HTTP non-2xx ─┐
   soft-error D2 ┴→ Build error log payload (success=false, tokens/coût null, latency=now−t0)
      → Call log_llm_call (erreur) [fire-and-forget]
      → Prepare llm_error payload → Call notify_system (llm_error) [fire-and-forget]
      → Error output { success:false, content:null, error }   (terminal — ne rejoint JAMAIS Output succès)
   (PAS de throw → error_handler ne fire pas → une seule notif)

Détail : 07 §B2.8 + §B2.11. [CORPUS]

Procédures et instructions rattachées

SYS_PQ_5 — Procédure de gestion des erreurs (Error Workflow, anti-récursion, fire-and-forget, renvois).
SYS_IQ_5 — Instruction : traiter un échec d'appel LLM / configurer l'Error Workflow (règles D1/D2 + anti-récursion) — embryon de catalogue.
(Pas de FQ dédié : l'enregistrement d'un échec EST une ligne de telemetrie.appels_llm avec success=false — cf. SYS_FQ_2.)

Interfaces amont/aval (handoffs)

Amont : tout workflow critique (Error Workflow configuré) ; SYS_PRO_1 (échec LLM). [CORPUS]
Aval : SYS_PRO_4 (émission des notifs workflow_error/llm_error) ; SYS_PRO_2 (ligne télémétrie success=false). [CORPUS]
Contrainte anti-récursion (ADR-034) : les workflows de livraison de notif (notify_system/notify_business/mattermost_post_message) ne portent pas error_handler ; error_handler avale sa propre notif (onError:continueRegularOutput). Sinon storm récursif (2026-06-02 12:02). [CORPUS]

Indicateurs (KPI)

KPI	Définition	Source
Taux d'échec LLM	`count(success=false)/count(*)`	`telemetrie.appels_llm` [CORPUS]
Nb exceptions `workflow_error` / jour	comptage notifs	`system-errors` [STANDARD]
MTTR (temps de réaction)	délai notif → résolution	manuel [À COMPLÉTER]
Récidive même nœud/workflow	regroupement des `workflow_error`	historique n8n [STANDARD]

Enregistrements

Lignes telemetrie.appels_llm avec success=false (cf. SYS_FQ_2). [CORPUS]
Messages system-errors (workflow_error / llm_error). [CORPUS]
Historique d'exécutions n8n (contexte d'erreur). [CORPUS]

Cas d'usage rattachés (UC-* du Recueil + nouveaux)

UC-SYS-08 (nouveau) — Tracer + notifier un échec LLM sans casser le workflow appelant (sortie {success:false}). [CORPUS]
UC-SYS-09 (nouveau) — Capturer une exception non gérée d'un workflow critique et la router vers system-errors. [CORPUS]
Lié : UC-A11 — une production insuffisante (pas une erreur) déclenche une relance (tentative), distincte d'un échec LLM. [CORPUS]

Roadmap (PQ/IQ/FQ restant à développer)

Fast-follow D3 — garde « parse JSON raté quand schéma attendu » (severity warning) dans Parse response d'agent_call. → futur SYS_IQ_5_2. [CORPUS]
Politique de rejeu des échecs LLM transitoires (retry/backoff) : non câblée v0 — à cadrer si le taux d'échec le justifie. [STANDARD] [À CONFIRMER]
Consolidation monitoring proactif sur Mattermost (Kuma → Mattermost, P10) : recâblage différé. [CORPUS]
Tableau de bord erreurs (web-app S0) : vue dédiée success=false + workflow_error (8bis+). [CORPUS]