Errori, retry, idempotenza e riconciliazione#

Un’integrazione affidabile non si misura dal solo happy path. Deve impedire il doppio effetto, distinguere timeout da fallimento e ricostruire lo stato quando core e provider non concordano.

Classi di errore#

Idempotenza#

L’idempotenza garantisce che la ripetizione della stessa richiesta non produca un secondo effetto.

Ogni comando mutativo dovrebbe usare:

• idempotency key stabile per il tentativo logico;
• hash del payload;
• riferimento interno;
• riferimento provider;
• risposta persistita.

Se la stessa chiave arriva con payload diverso, il provider e CertiExch devono rifiutare il comando.

Timeout#

Il timeout produce uno stato incerto, non necessariamente fallito.

richiesta inviata
→ timeout locale
→ esito esterno sconosciuto

Prima del retry:

1. usare lookup o stato provider;
2. cercare webhook/ricevute tardive;
3. verificare statement o chain;
4. confrontare request ID e idempotency key;
5. decidere l’azione con l’owner del dominio.

Duplicati#

Un duplicato può essere:

• stessa richiesta ricevuta due volte;
• stessa ricevuta notificata più volte;
• stesso evento rail letto da cursor sovrapposti;
• stesso file batch reimportato;
• stessa transition receipt ripresentata.

La gestione corretta è idempotente: conservare una sola conseguenza economica e registrare l’ulteriore consegna come duplicata, senza cancellare le prove.

Riconciliazione a tre livelli#

Per ogni integrazione confrontare:

1. stato interno: oggetto CertiExch e sua storia;
2. stato del provider: lookup, statement o chain;
3. ricevute/evidenze: messaggi autenticati e proof package.

Se due livelli concordano e uno diverge, non scegliere automaticamente la maggioranza: la fonte autoritativa dipende dal fatto da verificare.

Riconciliazioni principali#

Cash#

istruzione attesa
↔ prenotazione provider
↔ ricevuta finale
↔ statement/saldo

Paying agent#

obbligazioni
↔ istruzioni
↔ lordo/imposte/netto
↔ ricevute
↔ distribuzioni

Rail#

riserve del registro
↔ supply e saldi on-chain
↔ hold
↔ eventi acquisiti

Custodia#

posizione registrata
↔ statement custode
↔ wallet/ripartizione locale

Continuità/transizione#

manifest e hash
↔ ricevuta del destinatario
↔ stato ricostruito

Manual review#

Usare manual_review quando:

• l’effetto esterno può essere già avvenuto;
• le fonti non concordano;
• manca una ricevuta ma esiste un movimento;
• un evento post-finality richiede decisione;
• la correzione automatica potrebbe duplicare o perdere valore.

Correzione e reversal#

Non eliminare l’evento errato. Creare:

• oggetto di correzione;
• riferimento all’originale;
• motivazione;
• approvazione;
• effetto compensativo;
• nuova ricevuta;
• riconciliazione finale.

Il reversal tecnico non è sempre equivalente a una revoca giuridica o monetaria. Verificare la finalità raggiunta.

Incidenti di sicurezza#

Aprire un incidente quando si osservano:

• firma o token non validi;
• chain ID inatteso;
• contract address non autorizzato;
• risposta manipolata;
• replay fuori finestra;
• riferimento provider non riconosciuto;
• variazione dell’hash;
• credenziale esposta;
• tentativo di path traversal o file malevolo.

Separare l’incidente tecnico dalla rettifica economica: possono essere necessari entrambi.

Chiusura della riconciliazione#

Una riconciliazione è chiusa solo quando:

• differenza spiegata;
• effetto economico determinato;
• eventuale correzione eseguita;
• ricevute acquisite;
• stato dei sistemi allineato;
• owner e checker hanno approvato;
• evidenze conservate;
• azioni preventive assegnate.