Release Date: 10/07/2026


1. Resumo

A versão 4.6.0 traz mais transparência sobre falhas em transferências on-chain:

  • Motivo da falha em transferências on-chain — código de erro padronizado e descrição do que aconteceu, disponíveis na API, nos webhooks, na plataforma e no relatório Crypto Transactions.
  • Catálogo de erros na documentação da API — nova seção Transfer Errors, com o significado de cada código e como resolver.


2. Novidades

2.1 Motivo da falha em transferências on-chain

  • Toda transferência on-chain que falha passa a informar o motivo de forma padronizada: um código de erro estável e a descrição do que aconteceu.
  • O mesmo motivo aparece em todas as interfaces:
    • API: o motivo passa a vir na resposta de erro dos endpoints de transferência.
    • Webhooks: os eventos de falha passam a trazer o motivo da falha.
    • Plataforma: o toast de erro e um novo tooltip ao lado do status de falha em Activity > Crypto Transfers exibem a mensagem.
    • Relatório Crypto Transactions: novas colunas com o código, a mensagem e o erro original do provedor, preenchidas quando o status é de falha.

Nota Importante

  • O motivo é registrado no momento da falha. Transferências anteriores a esta versão não recebem novo motivo retroativamente.


2.2 Catálogo de erros de transferência na documentação da API

  • A documentação da API ganha a seção Transfer Errors, com uma linha por código de erro: o código (Error), o que aconteceu (Description) e o que fazer (How to resolve).
  • A seção de erros que já existia passa a se chamar General Errors, sem mudança de conteúdo.
  • Algumas mensagens contêm variáveis entre chaves, como {asset} e {network}, que são substituídas pelo valor real na resposta.


3. Impacto para Integrações

3.1 Motivo da falha nas respostas de erro de transferência

Pode impactar integrações.

  • O formato da resposta de erro dos endpoints de transferência não muda: os campos continuam os mesmos. O que muda é o conteúdo, que passa a trazer o motivo padronizado da falha dentro dos campos específicos:
    • error_code — novo código de erro padronizado.
    • message — o que aconteceu. Pode conter valores como o ativo e a rede envolvidos.

⚠️ Integrações que tomam decisões com base no texto de message ou em valores específicos de error_code retornados antes desta versão devem revisar essa lógica, já que os valores desses campos passam a seguir o catálogo de Transfer Errors.

Endpoints impactados:

  • Transações WMS
    • GET /v1/api/wms/transactions
  • Transações
    • GET /v2/api/transaction
    • GET /v1/api/transaction/{transactionId}


3.2 Campos de erro nos webhooks de transação

Pode impactar integrações.

  • Os eventos de falha TransactionCustody e WmsTransaction passam a incluir novo objeto error, com os campos code e message.
  • O nome dos eventos e os campos existentes não mudam; o objeto error é acrescentado.

⚠️ Integrações que validam o schema dos webhooks de forma estrita precisam aceitar o novo objeto error.


3.3 Plataforma e relatório Crypto Transactions

Não impacta integrações.

  • Três novas colunas no relatório Crypto Transactions, ao lado do status: Error Code, Error Message e Provider Error.
  • Toast e tooltip com a mensagem de erro.

Interfaces impactadas:

  • Activity > Crypto Transfers
  • Relatório Crypto Transactions


4. Referências

Documentação da API