🚧 Tratamento de Erros

Quando uma chamada à API falha, a DEX API retorna um código HTTP padrão e uma estrutura JSON explicativa.

1. Formato JSON de Erro

As respostas de erro contêm a seguinte estrutura:

{
  "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": {}
}

Campo	O que é	Como usar
`code`	Código fixo de domínio (ex: `PIX_KYC_REQUIRED`)	✅ Use este campo para programar caminhos de erro no seu código.
`message`	Explicação legível em linguagem humana	⚠️ Use apenas para logs de depuração no seu servidor. Não exiba cru para o cliente.
`traceId` / `requestId`	Identificadores de rastreamento do log	Envie no suporte da Ether para agilizar a resolução de problemas.

2. Códigos HTTP mais Comuns

400 Bad Request: Dados incorretos ou faltando. Veja o campo details para depurar os campos.
401 Unauthorized: Token ausente ou expirado. Gere um novo token (veja Autenticação).
403 Forbidden: Token válido, mas sem acesso (ex: conta no nível BASIC tentando fazer Pix).
422 Unprocessable Entity: Regras de negócio violadas (ex: saldo insuficiente).
429 Too Many Requests: Rate limits estourados. Use tempo de espera (Backoff) e aguarde.

3. Prefixo de Códigos de Domínio

O campo code ajuda a mapear mensagens amigáveis no seu aplicativo com base no módulo:

AUTH_*: Erros de tokens e autenticação.
PIX_*: Erros em depósitos, saques ou chaves Pix.
LDG_*: Erros do livro contábil (como LDG_INSUFFICIENT_FUNDS).
SWAP_*: Erros de cotação ou execução de Swap.
KYC_*: Erros de submissão de documentos e compliance.
PROFILE_*: Problemas cadastrais (como telefones ou CPFs duplicados).
PARTICIPANT_PORTAL_*: Erros na consulta de usuários vinculados (ver Portal de Leitura sobre Seus Usuários):
- PARTICIPANT_PORTAL_USER_OUT_OF_SCOPE — o userId consultado não pertence a você (403)
- PARTICIPANT_PORTAL_USER_NOT_FOUND — o userId informado não existe (404)
- PARTICIPANT_PORTAL_FEATURE_DISABLED — funcionalidade ainda não habilitada para o seu participante (403)
- PARTICIPANT_PORTAL_CONTEXT_REQUIRED — o token usado não é uma credencial de participante válida (403)

🔔 Eventos Assíncronos (Webhooks)