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

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}/ 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, 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 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: 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.

​

Próximos passos