Pattern circuit breaker per API di terze parti nei flussi visuali

Perché gli outage di API di terze parti rompono più di una funzionalità

Una singola API di terze parti spesso è al centro del lavoro quotidiano: gestisce pagamenti, verifica indirizzi, sincronizza inventario, invia messaggi, verifica identità. Quando quel fornitore ha problemi, raramente si rompe solo un pulsante. Può bloccare interi flussi che dipendono da quella risposta per procedere.

Ecco perché un circuit breaker è importante. Non è teoria: è un modo pratico per mantenere le operazioni core attive anche quando un’integrazione è instabile.

Lento e giù fanno danni diversi.

Quando un’API è lenta, il workflow prova comunque a proseguire, ma ogni passaggio aspetta. Gli utenti vedono schermate in caricamento, il supporto riceve ticket “è bloccato” e i job in background si accumulano. La lentezza è insidiosa perché può sembrare un problema del proprio sistema.

Quando un’API è giù, si ottengono timeout o errori netti. È più chiaro, ma spesso più pericoloso perché i workflow tendono a retryare. Quando molte richieste ritentano insieme, crei una tempesta di traffico che rende il recupero più difficile e può trascinarti giù anche tu.

I sintomi comuni emergono in fretta: timeout, code che continuano a crescere, aggiornamenti parziali e molta pulizia manuale.

Il vero danno è la reazione a catena. Se un provider di tariffe di spedizione è lento, la conferma dell’ordine rallenta perché il workflow non procede senza una quotazione. Se i pagamenti sono giù, il supporto potrebbe non riuscire a emettere rimborsi anche se tutto il resto funziona.

Non puoi fingere che gli outage non esistano. L’obiettivo è progettare i workflow con percorsi di fallback chiari, regole di blocco temporanee e alert, così il business può continuare a prendere ordini, servire clienti e registrare lavoro mentre l’integrazione si riprende.

Circuit breaker in termini semplici

Un circuit breaker è un interruttore di sicurezza per le chiamate API. Quando un servizio di terze parti inizia a fallire, il breaker impedisce al tuo workflow di martellarlo continuamente. Invece di trasformare un singolo outage in schermate lente, timeout e job bloccati, controlli il raggio d’azione del problema.

Un circuit breaker ha tre esiti semplici:

• Permettere la chiamata quando il vendor sembra sano.
• Bloccare la chiamata quando i fallimenti sono alti e prendere immediatamente un percorso di fallback.
• Tentare una chiamata di test limitata dopo una breve pausa per verificare se il vendor è tornato.

Se preferisci le etichette, sono “closed”, “open” e “half-open”. I nomi non sono la cosa importante. La prevedibilità sì. Quando un vendor è malfunzionante, il tuo workflow dovrebbe comportarsi allo stesso modo ogni volta.

Questo non nasconde gli errori. Registri comunque i fallimenti, mostri uno stato chiaro agli utenti o alle operazioni e alerti le persone giuste. Stai scegliendo di fallire velocemente, instradare il lavoro verso un’alternativa più sicura o aspettare brevemente prima di testare di nuovo.

Scegli quali chiamate non devono fermare il business

I circuit breaker funzionano meglio se sei selettivo. Non tutte le chiamate al vendor meritano protezione speciale. Inizia con i passaggi che, se bloccati, fermano soldi, ordini o l’accesso dei clienti.

Un metodo pratico è seguire una richiesta utente end-to-end. Dove un timeout costringerebbe l’utente ad abbandonare il compito o creerebbe un pasticcio che il team deve ripulire dopo?

Tipiche chiamate “non devono bloccare il lavoro core” includono pagamenti, spedizioni e fulfillment, login/SSO/MFA, OTP e messaggi di conferma, e controlli di conformità legati ad approvazioni.

Separa inoltre i passaggi user-facing dai job in background. Se qualcuno aspetta su una schermata di checkout, hai bisogno di una decisione rapida: successo, fallback o stop con messaggio chiaro. Per lavoro in background come la sincronizzazione dei numeri di tracking, retry più lenti vanno bene purché non blocchino il flusso principale.

Parti in piccolo per evitare di allargare troppo l’ambito. Proteggi prima 1–3 workflow, poi espandi.

Definisci cosa significa “fallback sicuro” prima di costruire. Buoni fallback sono specifici e testabili:

• Pagamenti: salva l’ordine come “payment pending” così il carrello non si perde.
• Spedizioni: usa una tariffa in cache, una tariffa piatta o conferma l’ordine e ritarda l’acquisto dell’etichetta.
• Identità: permetti il login con password quando SSO è giù, o passa alla verifica via email.
• Messaggistica: accoda gli SMS per dopo e fornisci un percorso alternativo quando possibile.

In AppMaster, nel Business Process Editor questo di solito diventa un ramo pulito: l’operazione core continua, mentre il passaggio dipendente dal vendor prende un’alternativa controllata.

Stati, soglie e timer che puoi spiegare

Un circuit breaker è un interruttore di sicurezza. La maggior parte del tempo lascia passare le chiamate. Quando il vendor inizia a fallire, si attiva per proteggere il tuo workflow dal tempo sprecato e dall’accumulo di errori.

I tre stati

Closed è la normalità. Chiami l’API e procedi.

Se i fallimenti superano una soglia, il breaker diventa Open. Smetti di chiamare il vendor per un breve periodo e instradi immediatamente a un fallback (valore in cache, lavoro accodato, flusso alternativo).

Dopo un periodo di cooldown, il breaker passa a Half-open. Permetti un piccolo numero di chiamate di test. Se riescono, torni a Closed. Se falliscono, torni a Open.

Cosa misurare

Usa segnali che rispecchiano come il vendor fallisce:

• Timeout
• Errori HTTP 5xx
• Aumento della latenza (troppo lento per essere utile)
• Errori di connessione/DNS
• 429 rate limit

In uno strumento di workflow visuale, questi si mappano spesso a controlli semplici: codice di stato, tempo trascorso e output di errore specifici.

Soglie iniziali e i due timer chiave

Inizia con numeri facili da spiegare, poi aggiustali in base al traffico reale. Esempi:

• Apri il breaker se 5–10 chiamate falliscono entro 30–60 secondi.
• Oppure apri se il 20%–40% delle chiamate fallisce in una finestra rolling.
• Tratta la latenza come fallimento quando supera ciò che il tuo processo può tollerare (spesso 2–5 secondi).

Poi imposta due timer:

• Cooldown (stato Open): spesso 30 secondi fino a 5 minuti.
• Finestra di test Half-open: permetti 1–5 chiamate di test, o una breve finestra come 10–30 secondi.

L’obiettivo è semplice: fallire velocemente quando il vendor è malsano, recuperare automaticamente quando torna.

Passo-passo: costruire un circuit breaker in un workflow visuale

La scelta di design più importante è prendere la decisione “chiamiamo il vendor adesso?” in un unico punto, non sparsa in ogni workflow.

1) Metti la chiamata al vendor dietro un blocco riusabile

Crea un sottoprocesso (un blocco di workflow riusabile) che ogni workflow usa quando ha bisogno di quel vendor. In AppMaster, questo si mappa naturalmente a un Business Process che puoi chiamare da endpoint o automazioni. Mantienilo stretto: input in, richiesta al vendor fuori, più un risultato chiaro di successo/fallimento.

2) Traccia i fallimenti con il tempo, non solo con i conteggi

Registra ogni esito con un timestamp. Memorizza cose come ultima riuscita, ultimo fallimento, fallimenti in una finestra, stato attuale e una scadenza di cooldown.

Persisti questi campi in una tabella così il breaker sopravvive ai riavvii e resta consistente tra istanze multiple. PostgreSQL via Data Designer si presta bene a questo.

3) Definisci i cambiamenti di stato da seguire ogni volta

Mantieni le regole semplici. Esempio: se 5 fallimenti accadono in 2 minuti, passa a Open. In Open salta la chiamata al vendor fino al termine del cooldown. Dopo il cooldown, vai in Half-open e permetti un tentativo controllato. Se funziona, chiudi il breaker. Se fallisce, riapri.

4) Dirama il workflow: percorso vendor vs fallback

Prima della richiesta al vendor, controlla lo stato memorizzato:

• Closed: chiama il vendor, poi aggiorna successo o fallimento.
• Open: salta la chiamata e esegui il fallback.
• Half-open: permetti un tentativo limitato, poi decidi se chiudere o riaprire.

Esempio: se un’API etichettatrice di spedizioni è giù, il fallback può creare l’ordine con stato “Label pending” e accodare un job di retry, invece di bloccare il checkout o il lavoro di magazzino.

5) Rendi lo stato condiviso tra i workflow

Se hai più workflow e server, devono leggere e scrivere lo stesso stato del breaker. Altrimenti un’istanza può continuare a martellare il vendor mentre un’altra ha già deciso di mettere in pausa.

Percorsi di fallback che mantengono il lavoro in movimento

Un circuit breaker serve solo se hai deciso cosa succede quando la chiamata è bloccata. Un buon fallback mantiene l’utente operativo, protegge i dati e rende la pulizia successiva prevedibile.

Scegli un fallback che corrisponda al lavoro. Se un provider di tariffe è giù, potresti non aver bisogno del prezzo esatto per accettare l’ordine. In un workflow visuale, dirama il passaggio API fallito verso un ramo di fallback che produce comunque un risultato utilizzabile.

Nella pratica, i fallback assomigliano spesso a:

• Usare un valore last-known in cache (con una finestra di freschezza chiara).
• Usare una stima sicura di default, chiaramente etichettata.
• Inviare a revisione manuale.
• Accodare il lavoro per un retry successivo (job asincrono).

L’esperienza utente conta quanto la logica. Non mostrare un errore vago. Spiega cosa è successo e cosa può fare l’utente: “Non siamo riusciti a confermare la tariffa ora. Puoi procedere con una stima di spedizione o salvare per revisione.”

Pianifica inoltre per outage brevi vs lunghi. Un outage breve (minuti) spesso significa “continua e ritenta in background”. Uno lungo (ore) può richiedere comportamenti più severi come più revisione manuale o approvazioni.

Infine, traccia ogni fallback così la riconciliazione è semplice. Al minimo, registra il tipo di fallback, i dettagli della richiesta originale, cosa è stato mostrato all’utente (e se era una stima) e uno stato per il follow-up.

Regole di blocco temporaneo e retry più intelligenti

I retry non controllati trasformano piccoli problemi del vendor in outage reali. Quando molti workflow ritentano simultaneamente, creano un picco (il problema della thundering herd). Il vendor rallenta, le code crescono e bruci i rate limit.

I retry dovrebbero essere prevedibili e limitati, e rispettare lo stato del breaker. Una politica pratica è:

• Mantieni i retry massimi bassi (spesso 2–3).
• Usa backoff esponenziale (es. 2s, 8s, 30s).
• Aggiungi jitter così i retry non si sincronizzano.
• Limita il tempo totale dei retry (es. 60–90 secondi).
• Se il breaker è Open, non retryare. Vai direttamente al fallback.

Il blocco temporaneo è correlato ma distinto. È per i casi in cui la risposta ti dice “non funzionerà adesso.” Regole comuni:

• 429 rate limit: blocca per il periodo Retry-After (o una finestra fissa sicura).
• 401/403 auth failure: blocca finché le credenziali non sono rinnovate, poi testa una volta.
• 5xx persistenti: blocca brevemente, poi permetti un piccolo test.

Durante un blocco, decidi cosa succede al lavoro già in corso: accodalo, instradalo altrove o degrada con grazia (es. accetta l’ordine ma rimanda “invia SMS”).

Alert che dicono cosa fare

Un circuit breaker è utile solo se le persone lo sentono rapidamente e sanno cosa fare. L’obiettivo non è rumore, ma un messaggio chiaro quando il comportamento cambia: le chiamate sono bloccate, i fallback sono attivi o il breaker è rimasto aperto più del previsto.

Trigger di default utili:

• Alert quando il breaker apre.
• Alert se rimane aperto oltre un limite di tempo.
• Alert su un aumento improvviso di errori anche prima dell’apertura.

Rendi gli alert azionabili. Includi vendor ed endpoint, stato corrente e quando è cambiato, cosa sentiranno gli utenti, cosa sta facendo ora il workflow (blocco, retry, fallback) e un passo suggerito.

Instrada gli alert per gravità. Un’API di arricchimento non critica può andare via email. Pagamenti, login o submission di ordini di solito meritano una paginazione. In AppMaster questo si mappa a rami che inviano email, Telegram o SMS basati su una flag di severità.

Monitora un piccolo set di metriche per vedere se ti stai riprendendo: chiamate bloccate e uso dei fallback per vendor sono spesso sufficienti.

Scenario di esempio: outage del vendor senza fermare gli ordini

Un guasto comune: il provider di tariffe di spedizione va giù proprio mentre i clienti fanno checkout. Se il tuo workflow insiste su tariffe live durante la creazione dell’ordine, un singolo outage può fermare gli ordini completamente.

In giornata normale, l’ordine viene creato, il workflow richiede tariffe live e l’ordine è salvato con il vettore e il prezzo scelto.

Quando il vendor inizia a fallire, le chiamate fanno timeout o ritornano 5xx. Quando viene raggiunta la soglia (ad esempio 5 fallimenti in 2 minuti), il breaker apre.

Mentre è Open, il workflow smette di chiamare il provider di spedizioni per una finestra breve (es. 10 minuti). Questo evita che un vendor in errore trascini il checkout per tutti.

Invece di bloccare il checkout, il fallback può:

• Applicare una tariffa flat (o una stima sicura).
• Creare comunque l’ordine.
• Segnarlo come “Shipping rate pending” per ricalcolo successivo.
• Salvare i dettagli dell’errore del vendor per follow-up.

In AppMaster, questo è un ramo chiaro nel Business Process Editor, supportato da campi Data Designer come shipping_rate_status e shipping_rate_source.

Controlli rapidi prima del rilascio

Un circuit breaker dovrebbe comportarsi allo stesso modo sotto stress come in demo. Prima del rilascio, conferma le basi:

• Soglie e cooldown sono documentati e facili da cambiare.
• Lo stato Open blocca le chiamate immediatamente (senza aspettare i timeout del vendor).
• Il comportamento del fallback è sicuro per denaro e promesse al cliente.
• Il probing Half-open è limitato a poche chiamate di test.
• I log rendono tempi e impatto facili da ricostruire.

Dedica tempo extra alla sicurezza dei fallback. Un fallback che “mantiene il lavoro” può anche creare rischio finanziario. Se il provider di pagamenti è giù, segnare un ordine come pagato è pericoloso. Un approccio più sicuro è “payment pending”, con messaggistica chiara al cliente.

Testa il recovery intenzionalmente. Forza i fallimenti, osserva il breaker aprirsi, aspetta il cooldown e conferma che Half-open manda solo una piccola sonda. Se ha successo, dovrebbe chiudersi rapidamente. Se fallisce, dovrebbe riaprirsi senza sommergere il vendor.

I log dovrebbero rispondere, in meno di un minuto: chi è stato impattato, quando è iniziato, quale step del workflow ha attivato il breaker e quale fallback è stato usato.

Prossimi passi: implementare il pattern in AppMaster

Scegli un’integrazione che può danneggiare le operazioni quotidiane se fallisce (pagamenti, etichette di spedizione, SMS, sincronizzazione CRM). Costruisci il breaker end-to-end per quella singola chiamata prima. Quando il team si fida del comportamento, ripeti lo stesso template per il prossimo vendor.

In AppMaster, modella lo stato del breaker in PostgreSQL usando il Data Designer. Mantienilo semplice: un record per vendor (o endpoint) con campi come state, failure_count, last_failure_at, open_until e un breve last_error.

Poi implementa la logica nel Business Process Editor con ramificazioni leggibili. La chiarezza batte l’astuzia.

Ordine pratico di costruzione:

1. Controlla lo stato del breaker e blocca le chiamate quando open_until è nel futuro.
2. Chiama l’API vendor e cattura sia gli output di successo che di errore.
3. In caso di successo, resetta i contatori e chiudi il breaker.
4. In caso di fallimento, incrementa i contatori e apri il breaker quando le soglie sono raggiunte.
5. Dirama i flussi user-facing verso un fallback (accoda lavoro, usa dati in cache o permetti il processo manuale).

Documenta la decisione di fallback in linguaggio semplice così support e ops sanno cosa vede l’utente.

Quando il breaker apre, notifica un owner usando i moduli di messaggistica di AppMaster (email, SMS, Telegram). Includi ciò che conta: vendor, endpoint, stato e la prima azione consigliata.

Se stai costruendo questi workflow in AppMaster, appmaster.io è un punto pratico da cui partire perché lo stesso Business Process visuale può alimentare endpoint, job in background e alerting con uno stato del breaker condiviso.