Tratamento de Erros

A DEX API utiliza os padrões de HTTP Status Codes do mercado para informar o resultado de suas operações. Sempre que uma operação falhar, a API retornará um código HTTP pertencente às famílias 4xx (erros causados pelo cliente) ou 5xx (erros internos no servidor ou integrações).

Além do código HTTP, nós incluímos um envelope JSON padronizado que entrega a você o código exato do erro e detalhes extras para depuração.

1. Estrutura Padrão de Erro

Toda resposta de erro na nossa API B2B possuirá o seguinte formato JSON:

{
  "code": "AUTH_TOKEN_INVALID",
  "message": "Token de autenticação inválido ou expirado",
  "timestamp": "2026-06-17T12:00:00.000Z",
  "traceId": "otel-trace-id-123456",
  "requestId": "req-uuid-v7-123456",
  "details": {
    "retryAfter": 60
  }
}

Campo	Descrição
`code`	(String) Um código constante e imutável que identifica categoricamente o erro (Ex: `PIX_KYC_REQUIRED`). Seu sistema deve basear a lógica de tratamento em cima deste código, e não do texto de `message`.
`message`	(String) Uma descrição em texto legível explicando o erro. Útil para o log do seu servidor, mas não é recomendado exibi-la crua para o usuário final.
`timestamp`	(String) Momento exato em que o erro ocorreu (ISO 8601).
`traceId` / `requestId`	(String) IDs únicos de rastreamento. Se você precisar abrir um ticket de suporte conosco, o envio destes campos acelera imensamente a resolução.
`details`	(Objeto) Um dicionário opcional contendo contextos extras sobre a falha (ex: campos que falharam na validação, tempo de espera para re-tentar).

2. Códigos HTTP mais Comuns

Sua aplicação B2B deve estar preparada para lidar com os seguintes cenários gerais:

400 Bad Request: A requisição está mal formatada. Geralmente significa que o body JSON está inválido ou parâmetros obrigatórios faltaram. Verifique o campo details no retorno.
401 Unauthorized: O seu Access Token não foi enviado, é inválido ou expirou. Você deve gerar um novo token e re-tentar a operação.
403 Forbidden: Você tem um token válido, mas sua conta ou o usuário relacionado não tem permissão para a operação. Exemplo comum: Tentar solicitar um saque Pix sem o usuário ter finalizado o KYC (FULL).
404 Not Found: O recurso que você tentou acessar não existe. (Ex: ID da transação ou telefone no DICT não encontrados).
422 Unprocessable Entity: O formato dos dados está correto, mas as regras de negócio impedem o processamento (Ex: Saldo insuficiente ou cotação de Swap expirada).
429 Too Many Requests: Você extrapolou o Rate Limit da API. Implemente Exponential Backoff.
500 Internal Server Error: Ocorreu um erro interno na EtherBank. Retente mais tarde.
503 Service Unavailable: Um provedor crítico da EtherBank está fora do ar (ex: Cryptobrokers ou Banco Central/Pix). Retente de forma espaçada.

3. Códigos de Domínio (Business Errors)

Para facilitar a integração e o retorno amigável nos seus Frontends, agrupamos os códigos (code) que retornam dentro do envelope em categorias:

AUTH_*: Erros relacionados à validação de chaves e expiração de acessos.
PIX_*: Erros exclusivos da rede Pix (ex: chave inválida, limites de transferência BC, usuário sem KYC).
LDG_*: Erros de Ledger (saldos e transferências). Exemplo: LDG_INSUFFICIENT_FUNDS.
SWAP_*: Problemas com cotações e liquidez.

Dica de UX: Use a propriedade code para mapear de forma centralizada mensagens amigáveis ou chaves de internacionalização (i18n) nos seus próprios Frontends, garantindo que a comunicação final esteja alinhada à sua marca.

Autenticação

Evento Webhook