> ## 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.

# Solução de problemas de KYT: erros comuns e correções

> Corrija problemas comuns de KYT na Didit: colisões de txn_id, regras que não disparam, timeouts de AML, falhas de assinatura de webhook e moedas.

Uma referência dos problemas mais comuns no Monitoramento de transações, com sintoma, causa e solução.

## Erro de `txn_id` duplicado

**Sintoma.** O envio de uma transação retorna `400` com `A transaction with this transaction_id already exists.` no campo `transaction_id`, ou `409` quando duas requisições idênticas concorrem entre si.

**Causa.** O `txn_id` (o `transaction_id` que você envia) é único por aplicação.
A Didit rejeita uma segunda transação com o mesmo `transaction_id` e não retorna o registro existente.

**Solução.**

* Gere o `txn_id` de forma determinística do seu lado (por exemplo, use o ID da transação no seu próprio banco de dados).
* Ao receber um `400` ou `409` por `transaction_id` duplicado durante uma nova tentativa, consulte a transação existente em vez de reenviá-la: leia-a com [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/pt-br/management-api/transactions/get) usando o `uuid` da primeira resposta, ou use o `transaction_id` (o uuid da Didit) que o webhook `transaction.created` traz junto com o seu `txn_id`.
* Se a requisição não era uma nova tentativa, atribua à nova transação o seu próprio `transaction_id`.

## Regra não dispara

**Sintoma.** Você criou uma regra que deveria corresponder, mas nenhuma transação a exibe em `rule_runs[]` com `matched: true`.

**Causas e soluções.**

* **A aplicação está em modo sandbox**: uma aplicação em sandbox ignora a avaliação de regras, a Análise AML, o faturamento e os webhooks `transaction.created` e `transaction.status.updated`. As trocas de Travel Rule continuam sendo executadas quando habilitadas, com o [VASP de teste da Didit](https://docs.didit.me/pt-br/transaction-monitoring/travel-rule-sandbox.md), e entregam webhooks `travel_rule.status.updated` marcados com `environment: sandbox`. `rule_runs` volta vazio e a pontuação permanece `0`, seja qual for o modo das suas regras, e a transação permanece `APPROVED`, a menos que uma transferência de Travel Rule prestes a expirar aplique o seu `timeout_outcome`. Verifique `environment` na resposta da transação: `"sandbox"` significa que ela nunca foi avaliada. Consulte [Monitoramento de transações em sandbox](https://docs.didit.me/pt-br/integration/sandbox-testing.md#monitoramento-de-transações-no-sandbox) para saber como validar uma regra antes de colocá-la em produção.
* **O modo da regra é `DISABLED` ou `TEST`**: verifique *Rules → \[rule] → Mode*. Apenas regras `ACTIVE` contribuem para a pontuação; regras `TEST` são avaliadas, mas não afetam o status.
* **O filtro de escopo exclui a transação**: por exemplo, um escopo definido como `transaction_type = finance` não corresponde a transações `travelRule`.
* **A janela de agregação é menor do que o necessário**: uma regra de "20 transações em 30 dias" não corresponde depois de apenas 15 transações.
* **O campo da condição é nulo**: por exemplo, sua regra verifica `counterparty.country_code`, mas você não enviou uma contraparte.
* **Conversão de moeda**: a regra aplica limiares sobre `amount_in_default_currency`; se a moeda padrão da sua aplicação for diferente da moeda da transação, o valor convertido pode ficar abaixo do limiar.

Use o recurso *Rules → \[rule] → Backtest* para reproduzir uma transação passada e ver por que a regra disparou ou não.

## Regra dispara em tudo

**Sintoma.** Uma regra dispara em 90%+ das transações, e a sua fila de revisão fica sobrecarregada.

**Causa.** As condições são amplas demais ou os limiares são baixos demais.

**Solução.**

* Adicione filtros de `scope` para restringir a aplicabilidade (por exemplo, apenas transações de saída ou apenas determinados tipos de transação).
* Aumente os limiares (valores, contagens de transações em determinado período).
* Coloque a regra em modo `TEST` por uma semana: analise os `rule_runs` para ver a taxa de correspondência e restrinja as condições antes de reativá-la.

## Tempo esgotado na triagem de cripto

**Sintoma.** A transação foi concluída com `status: APPROVED`, mas o array `provider_results[]` mostra `status: FAILED` para uma carteira, um hash de transação ou um provedor de triagem de cripto.

**Causas.**

* A API do provedor ficou indisponível por um breve período.
* A consulta excedeu o tempo limite (normalmente cerca de 10 s).

**Solução.**

* As transações nunca falham por causa de problemas nos provedores: o enriquecimento é feito conforme possível.
* Se um provedor específico falhar repetidamente, verifique a página de status dele ou abra um chamado de suporte.
* Considere configurar as preferências de provedores em *Settings → Transaction Monitoring → Providers* para direcionar as consultas a provedores alternativos.

## Enriquecimento de IP ausente

**Sintoma.** O `applicant.ip_enrichment` de uma transação está ausente ou incompleto.

**Causas.**

* Não há `applicant.device.ip` no envio.
* O IP é privado ou reservado (não roteável).
* Todos os provedores de enriquecimento estavam temporariamente indisponíveis.

**Solução.**

* Capture o IP de quem faz o envio no seu cliente ou servidor e informe-o em todas as transações.
* Use apenas IPs roteáveis: a Didit ignora faixas privadas sem avisar.
* Verifique *Settings → Status* no console para verificar o status dos provedores.

## Assinatura do webhook não confere

**Sintoma.** Seu endpoint rejeita eventos porque a assinatura não confere.

**Causas.**

* O corpo bruto foi modificado (JSON serializado novamente com espaçamento diferente).
* Segredo incorreto.
* Vários destinos com a mesma URL: as assinaturas são diferentes para cada destino.

**Solução.**

* **Calcule a assinatura sobre o corpo bruto da requisição**, e não sobre o JSON já interpretado. Muitos frameworks oferecem um middleware de corpo bruto.
* Troque o segredo se ele tiver sido comprometido: *Webhook destinations → \[destino] → Rotate secret*.
* Mantenha um destino por URL para evitar confusão entre segredos.

## Webhook não chega

**Sintoma.** As transações estão sendo criadas, mas os webhooks nunca chegam.

**Causas.**

* O `enabled` do destino está como `false`.
* A URL não está acessível publicamente.
* O destino foi desativado automaticamente após falhas repetidas.
* O evento não está em `subscribed_events`.

**Solução.**

* Envie um evento de teste: *Webhook destinations → \[destino] → Send test*.
* Verifique as entregas recentes: *Webhooks → \[destino] → Deliveries*. Veja as respostas 4xx/5xx com corpo e cabeçalhos.
* Reative os destinos desativados.

## Conversão de moeda parece errada

**Sintoma.** O `amount_in_default_currency` não corresponde à taxa que você esperava.

**Causas.**

* A taxa de câmbio é a taxa média de mercado na `txn_date`.
* Transações com data retroativa usam a taxa histórica daquela data.
* Algumas moedas (câmbio exótico) têm intervalos de atualização mais espaçados.

**Solução.**

* Use `amount` e `currency` (nativos) para exibição.
* Use `amount_in_default_currency` apenas para os limiares internos das regras.
* Para fins de auditoria, o registro da transação fixa a taxa de conversão usada no momento da avaliação.

## Contraparte não corresponde à minha lista de bloqueio

**Sintoma.** Você adicionou uma empresa à lista de bloqueio pelo `vendor_data`, mas uma transação com essa contraparte ainda foi processada.

**Causas.**

* A contraparte no payload da transação não tem `vendor_data` e foi armazenada como snapshot externo.
* O uso de maiúsculas e minúsculas em `vendor_data` é diferente.

**Solução.**

* Sempre envie `counterparty.vendor_data` quando a contraparte for uma entidade da sua plataforma.
* Use as mesmas maiúsculas e minúsculas em todos os lugares: `vendor_data` diferencia maiúsculas de minúsculas.

## Transações AWAITING\_USER paradas

**Sintoma.** As transações ficam paradas em `AWAITING_USER` porque o usuário nunca conclui a sessão de remediação.

**Causas.**

* O usuário não abriu a URL da sessão de remediação.
* A sessão de remediação expirou.
* A transação é uma transferência Travel Rule que uma regra da biblioteca, como `travel-rule-pending-action`, moveu para `AWAITING_USER`: a Didit não cria sua sessão de remediação padrão para uma transação Travel Rule, então, a menos que a regra indique um fluxo de remediação próprio, não há link para entregar.

**Solução.**

* O `remediation_session_url` da resposta da transação é o link a ser entregue. Entregue-o novamente ao usuário.
* Para uma transação Travel Rule, resolva a transferência pela aba **Travel Rule** e depois altere você mesmo o status da transação, porque resolver a transferência não tira, por si só, a transação de `AWAITING_USER`.
* As sessões de remediação seguem o mesmo padrão do [guia de início rápido de KYC](https://docs.didit.me/pt-br/getting-started/quick-start.md): assine os webhooks de conclusão.
* Defina um tempo limite no seu próprio sistema para expirar transações inativas caso a remediação nunca seja concluída.

## Limite de requisições ao criar

**Sintoma.** `429 Too Many Requests` durante picos de alto volume.

**Solução.**

* Respeite o cabeçalho `Retry-After`.
* Limite a taxa de requisições no lado do cliente para tráfego em picos.
* Entre em contato com o suporte para obter limites maiores com base em volume comprovado em produção.

Consulte [limite de requisições](https://docs.didit.me/pt-br/integration/rate-limiting.md).

## Próximos passos

> [card] [Guia de integração](https://docs.didit.me/pt-br/transaction-monitoring/integration-guide.md)
>
> Padrões completos de integração.

> [card] [Regras](https://docs.didit.me/pt-br/transaction-monitoring/rules.md)
>
> Como funciona a avaliação de regras.

> [card] [Webhooks](https://docs.didit.me/pt-br/transaction-monitoring/webhooks.md)
>
> Funcionamento dos webhooks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.