> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Risoluzione dei problemi KYT: errori comuni e soluzioni > Risolvi i problemi comuni del KYT di Didit: collisioni txn_id, regole non attivate, timeout AML, firme webhook errate, valute. Cause e soluzioni. Un riferimento dei problemi più comuni di Monitoraggio delle transazioni, con sintomo, causa e soluzione. ## Errore `txn_id` duplicato **Sintomo.** L'invio di una transazione restituisce `400` con `A transaction with this transaction_id already exists.` sul campo `transaction_id`, oppure `409` quando due richieste identiche si sovrappongono. **Causa.** `txn_id` (il `transaction_id` che invii) è univoco per applicazione. Didit rifiuta una seconda transazione con lo stesso `transaction_id` e non restituisce il record esistente. **Soluzione.** * Genera `txn_id` in modo deterministico dal tuo lato (ad esempio usando l'ID della tua tabella delle transazioni). * In caso di `400` o `409` per un `transaction_id` duplicato durante un nuovo tentativo, cerca la transazione esistente invece di inviarla di nuovo: leggila con [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/it/management-api/transactions/get) usando l'`uuid` della prima risposta, oppure usa il `transaction_id` (l'uuid di Didit) che il webhook `transaction.created` riporta accanto al tuo `txn_id`. * Se la richiesta non era un nuovo tentativo, assegna alla nuova transazione un proprio `transaction_id`. ## La regola non si attiva **Sintomo.** Hai creato una regola che dovrebbe corrispondere, ma nessuna transazione la mostra in `rule_runs[]` con `matched: true`. **Cause e soluzioni.** * **L'applicazione è in modalità sandbox**: un'applicazione sandbox salta la valutazione delle regole, lo screening AML, la fatturazione e i webhook `transaction.created` e `transaction.status.updated`. Gli scambi Travel Rule vengono comunque eseguiti quando sono abilitati, verso il [Didit Test VASP](https://docs.didit.me/it/transaction-monitoring/travel-rule-sandbox.md), e inviano webhook `travel_rule.status.updated` contrassegnati con `environment: sandbox`. `rule_runs` torna vuoto e il punteggio resta `0`, qualunque sia la modalità delle tue regole, e la transazione resta `APPROVED` a meno che un trasferimento Travel Rule in scadenza non applichi il tuo `timeout_outcome`. Controlla `environment` nella risposta della transazione: `"sandbox"` significa che non è mai stata valutata. Consulta [Transaction Monitoring in sandbox](https://docs.didit.me/it/integration/sandbox-testing.md#monitoraggio-delle-transazioni-nella-sandbox) per capire come validare una regola prima che vada in produzione. * **La modalità della regola è `DISABLED` o `TEST`**: controlla *Rules → \[rule] → Mode*. Solo le regole `ACTIVE` contribuiscono al punteggio; le regole `TEST` vengono valutate ma non influiscono sullo stato. * **Il filtro di ambito esclude la transazione**: ad esempio, uno scope impostato su `transaction_type = finance` non corrisponde alle transazioni `travelRule`. * **La finestra di aggregazione è più corta del necessario**: una regola "20 transazioni in 30 giorni" non si attiva dopo sole 15 transazioni. * **Il campo della condizione è null**: ad esempio, la tua regola verifica `counterparty.country_code` ma non hai inviato una controparte. * **Conversione valutaria**: la regola usa come soglia `amount_in_default_currency`; se la valuta predefinita della tua applicazione è diversa dalla valuta della transazione, l'importo convertito potrebbe risultare sotto la soglia. Usa la funzione *Rules → \[rule] → Backtest* per rieseguire una transazione passata e capire perché la regola si è attivata o no. ## La regola si attiva su tutto **Sintomo.** Una regola si attiva sul 90%+ delle transazioni: la tua coda di revisione è sommersa. **Causa.** Le condizioni sono troppo ampie oppure le soglie sono troppo basse. **Soluzione.** * Aggiungi filtri `scope` per restringere l'applicabilità (ad esempio solo transazioni in uscita, solo determinati tipi di transazione). * Alza le soglie (importi, numero di operazioni nel periodo). * Imposta la regola in modalità `TEST` per una settimana: analizza i `rule_runs` per vedere il tasso di corrispondenza e restringi le condizioni prima di riattivarla. ## Timeout dello screening crypto **Sintomo.** La transazione è completata con `status: APPROVED`, ma l'array `provider_results[]` mostra `status: FAILED` per un wallet, un hash di transazione o un provider di screening crypto. **Cause.** * L'API del provider è stata brevemente non disponibile. * La query è scaduta (in genere dopo circa 10 s). **Soluzione.** * Le transazioni non falliscono mai a causa dei provider: l'arricchimento viene eseguito al meglio delle possibilità. * Se un provider specifico fallisce ripetutamente, controlla la sua pagina di stato o apri un ticket di supporto. * Valuta di configurare le preferenze dei provider in *Settings → Transaction Monitoring → Providers* per instradare le richieste verso provider alternativi. ## Arricchimento IP mancante **Sintomo.** `applicant.ip_enrichment` di una transazione è assente o parziale. **Cause.** * Nell'invio manca `applicant.device.ip`. * L'IP è privato o riservato (non instradabile). * Tutti i provider di arricchimento erano temporaneamente non disponibili. **Soluzione.** * Acquisisci l'IP di chi invia nel tuo client o server e passalo in ogni transazione. * Usa solo IP instradabili: Didit ignora silenziosamente gli intervalli privati. * Controlla lo stato dei provider in *Settings → Status* nella console. ## Mancata corrispondenza della firma del webhook **Sintomo.** Il tuo endpoint rifiuta gli eventi perché la firma non corrisponde. **Cause.** * Il corpo grezzo è stato modificato (JSON serializzato di nuovo con spaziatura diversa). * Segreto errato. * Più destinazioni webhook con lo stesso URL: le firme sono diverse per ogni destinazione. **Soluzione.** * **Calcola la firma sul corpo grezzo della richiesta**, non sul JSON analizzato. Molti framework espongono un middleware per il corpo grezzo. * Ruota il segreto se è compromesso: *Webhook destinations → \[destination] → Rotate secret*. * Mantieni una sola destinazione per URL, per evitare confusione tra i segreti. ## Il webhook non arriva **Sintomo.** Le transazioni vengono create, ma i webhook non arrivano mai. **Cause.** * `enabled` della destinazione è `false`. * L'URL non è raggiungibile pubblicamente. * La destinazione webhook è stata disattivata automaticamente dopo ripetuti errori. * L'evento non è incluso in `subscribed_events`. **Soluzione.** * Invia un evento di test: *Webhook destinations → \[destination] → Send test*. * Controlla le consegne recenti: *Webhooks → \[destination] → Deliveries*. Vedrai le risposte 4xx/5xx con corpo e intestazioni. * Riattiva le destinazioni webhook disattivate. ## La conversione valutaria sembra errata **Sintomo.** `amount_in_default_currency` non corrisponde al tasso che ti aspetti. **Cause.** * Il tasso di cambio è il tasso medio di mercato alla data `txn_date`. * Le transazioni retrodatate usano il tasso storico di quella data. * Alcune valute (valute esotiche) hanno intervalli di aggiornamento più ampi. **Soluzione.** * Usa `amount` e `currency` (valuta originale) per la visualizzazione. * Usa `amount_in_default_currency` solo per le soglie delle regole interne. * Ai fini di audit, il record della transazione conserva il tasso di conversione utilizzato al momento della valutazione. ## Controparte non corrispondente alla mia blocklist **Sintomo.** Hai inserito in blocklist un'azienda tramite `vendor_data`, ma una transazione con quella controparte è comunque andata a buon fine. **Cause.** * La controparte nel payload della transazione non ha `vendor_data`: è memorizzata come snapshot esterno. * Il `vendor_data` differisce per maiuscole e minuscole. **Soluzione.** * Passa sempre `counterparty.vendor_data` quando la controparte è un'entità presente sulla tua piattaforma. * Usa la stessa combinazione di maiuscole e minuscole ovunque: `vendor_data` distingue tra maiuscole e minuscole. ## Transazioni AWAITING\_USER bloccate **Sintomo.** Le transazioni restano bloccate in `AWAITING_USER` perché l'utente non completa mai la sessione di rimedio. **Cause.** * L'utente non ha aperto l'URL della sessione di rimedio. * La sessione di rimedio è scaduta. * La transazione è un trasferimento Travel Rule che una regola della libreria, come `travel-rule-pending-action`, ha spostato in `AWAITING_USER`: Didit non crea la sessione di rimedio predefinita per una transazione Travel Rule, quindi, a meno che la regola non indichi un proprio workflow di rimedio, non esiste alcun link da inviare. **Soluzione.** * Il `remediation_session_url` nella risposta della transazione è il link da inviare. Invialo di nuovo all'utente. * Per una transazione Travel Rule, risolvi il trasferimento dalla scheda **Travel Rule**, poi modifica tu lo stato della transazione, perché la risoluzione del trasferimento non sposta da sola la transazione fuori da `AWAITING_USER`. * Le sessioni di rimedio seguono lo stesso schema della [guida rapida KYC](https://docs.didit.me/it/getting-started/quick-start.md): sottoscrivi i webhook di completamento. * Imposta nel tuo sistema un timeout per far scadere le transazioni ferme se il rimedio non viene mai completato. ## Limite di frequenza sulla creazione **Sintomo.** `429 Too Many Requests` durante picchi di volume elevato. **Soluzione.** * Rispetta l'intestazione `Retry-After`. * Limita il ritmo delle richieste lato client durante i picchi di traffico. * Contatta il supporto per limiti più alti, in base a un volume di produzione comprovato. Vedi [limitazione della frequenza](https://docs.didit.me/it/integration/rate-limiting.md). ## Prossimi passi > [card] [Guida all'integrazione](https://docs.didit.me/it/transaction-monitoring/integration-guide.md) > > Schemi di integrazione completi. > [card] [Regole](https://docs.didit.me/it/transaction-monitoring/rules.md) > > Come funziona la valutazione delle regole. > [card] [Webhook](https://docs.didit.me/it/transaction-monitoring/webhooks.md) > > Meccanismi dei webhook. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.