Distingui errore, rifiuto ed esito sconosciuto
Se un’API rifiuta un dato perché manca un campo, ripetere la stessa richiesta non lo corregge. Se il servizio risponde lentamente e il collegamento scade, l’operazione potrebbe essere stata eseguita senza che sia arrivata la conferma. Trattare entrambi i casi come “riprova” può produrre risultati sbagliati.
Per ogni integrazione, definisci stati osservabili: ricevuto, validato, in lavorazione, completato, rifiutato e da verificare. Conserva il riferimento dell’operazione esterna quando esiste. Chi interviene deve poter capire quale passo è riuscito, non soltanto leggere una generica notifica “flusso fallito”.
Ripetere senza moltiplicare gli effetti
L’idempotenza permette di trattare tentativi della stessa operazione come un’unica intenzione. Amazon descrive questo principio per rendere più sicuri i retry. Il supporto concreto dipende dall’API: alcune accettano una chiave, altre richiedono verifiche o un registro delle operazioni. Non presumere che qualunque connettore impedisca automaticamente i duplicati.
Se l’API offre una chiave di idempotenza, riutilizzala soltanto per il medesimo tentativo logico secondo il suo contratto. Una richiesta diversa non dovrebbe ereditare la chiave di una precedente. La documentazione Stripe è un esempio di regole specifiche del fornitore, non una garanzia applicabile ad altri servizi.
Fai scorrere la tabella per confrontare tutte le colonne.
| Esito | Azione proposta | Da evitare |
|---|---|---|
| Dato non valido | Correggere o inviare a revisione | Ripetere senza cambiare nulla |
| Limite temporaneo o indisponibilità | Retry limitato con attesa, secondo il contratto API | Tentativi infiniti o tutti simultanei |
| Timeout dopo un invio | Verificare stato o usare deduplicazione prevista | Creare una nuova operazione alla cieca |
| Passaggi parzialmente completati | Riconciliare gli stati e riprendere dal punto sicuro | Rieseguire l’intero flusso senza controllo |
Esempio illustrativo: ordine creato, risposta persa
Primo tentativo
Il workflow invia un ordine al gestionale. Il gestionale lo registra, ma la risposta non raggiunge il workflow entro il tempo previsto.
Verifica
Il workflow mantiene la stessa identità dell’operazione. Se il contratto lo permette, verifica lo stato tramite riferimento esterno o ripete con la chiave prevista.
Intervento
Se l’esito resta incerto, il caso entra in una coda con dati e tentativi visibili. Una persona controlla il gestionale prima di autorizzare una nuova creazione.
Un retry sicuro non è una promessa di esecuzione “esattamente una volta” per l’intero sistema. Occorre verificare i confini e le garanzie di ogni componente.
Controlla periodicamente che i sistemi concordino
La riconciliazione confronta gli esiti attesi con quelli registrati: un caso completato nel workflow deve avere il riferimento corretto nel gestionale, e viceversa. Definisci quali divergenze contano, chi le esamina e come si correggono senza perdere traccia della modifica.
Non ogni passo può essere annullato. Una bozza può essere eliminata; un’email inviata non può essere recuperata con la stessa facilità. Progetta ordine delle azioni e interventi correttivi in base a questa differenza. Un rollback del codice non annulla gli effetti già prodotti nei sistemi esterni.
Le prove da chiedere prima del rilascio
Documenta queste prove insieme al runbook operativo. Il valore non è soltanto tecnico: il team deve sapere come recuperare una pratica senza chiedere al fornitore di ricostruire ogni incidente da zero.
- Simulare timeout prima e dopo la registrazione esterna.
- Consegnare due volte lo stesso evento e verificare il risultato.
- Fermare il processo tra due sistemi e riprenderlo senza duplicati.
- Esaurire i retry e verificare coda, avviso e assegnazione del caso.
- Confrontare stati esterni e interni dopo una correzione manuale.
Un modello su cui lavorare.
Mappa delle integrazioni
Una scheda per collegamento, con campi mappati, autorizzazioni, gestione dei duplicati e un controllo di riconciliazione.
Scarica il modello MarkdownRegistro delle eccezioni
Una coda di eccezioni con stato, priorità, responsabile e prova di chiusura; le ricorrenze alimentano il miglioramento del flusso.
Scarica il modello MarkdownRunbook di gestione operativa AI
Istruzioni accessibili al personale incaricato: segnali, allarmi, diagnosi iniziale, ripristino e revisione periodica.
Scarica il modello MarkdownDomande pratiche
Un connettore pronto garantisce assenza di duplicati?
No. Verifica il comportamento della specifica operazione, inclusi retry, timeout, durata delle chiavi e gestione degli eventi duplicati. Un’integrazione va provata sul percorso completo.
Dobbiamo riprovare tutti gli errori?
No. Errori permanenti e dati invalidi richiedono correzione. Gli esiti incerti richiedono verifica; gli errori transitori possono consentire retry limitati secondo le regole del servizio.
Perché serve una coda manuale?
Alcuni esiti non possono essere risolti automaticamente con evidenza sufficiente. Una coda assegnata, con storico e riferimenti, permette un recupero controllato invece di un nuovo invio alla cieca.
Riferimenti e metodo
Principio di idempotenza e gestione dei retry. L’esempio d’ordine è illustrativo.
Esempio concreto di un contratto di idempotenza; le regole vanno verificate per ogni API utilizzata.