Tratamento de erros

Toda falha na API retorna um corpo JSON padronizado com uma mensagem legível e um error_code estável. O status HTTP também reflete o erro (não é sempre 200). Trate os erros pelo error_code, ele NÃO muda entre idiomas nem entre versões.

HTTP 422
{
  "ok": false,
  "error": "Chave PIX não encontrada.",
  "error_code": "pix_key_not_found"
}

• ok — sempre false em caso de erro.
• error — mensagem legível (localizada por idioma). Boa para exibir/logar; NÃO use para lógica.
• error_code — slug estável para você tratar por código (switch/if). É a fonte da verdade.

Status HTTP

• 400 — requisição inválida (dados/campos).
• 401 — credenciais ausentes ou inválidas.
• 403 — sem permissão, IP não autorizado ou recurso desativado.
• 422 — dado recusado no processamento (ex.: chave não encontrada, saldo insuficiente).
• 429 — muitas tentativas. Aguarde e tente de novo.
• 500 / 503 — erro interno ou serviço temporariamente indisponível.

Códigos de erro

O mesmo error_code pode aparecer em rotas diferentes. Trate sempre pelo código.

Autenticação e acesso

• missing_credentials401— Client ID/Secret ausentes no cabeçalho.
• invalid_credentials401— Client ID/Secret inválidos.
• key_inactive403— Chave de API inativa.
• permission_denied403— A chave não tem a permissão exigida (cashin/cashout/balance).
• ip_not_configured403— Cash-out sem IP na allowlist da chave.
• ip_not_allowed403— IP de origem fora da allowlist (ou não IPv4).
• invalid_account403— Conta associada à chave inválida.
• rate_limited429— Muitas solicitações em pouco tempo.

Chave / recebedor (PIX)

• pix_key_not_found422— Chave PIX informada não existe no DICT.
• pix_key_invalid422— Chave PIX com formato inválido.
• pix_key_type_invalid422— Tipo de chave não aceito para este destino.
• invalid_document422— CPF/CNPJ inválido ou não confere com a chave.
• name_mismatch422— Nome/documento do recebedor não confere com a chave.
• recipient_cannot_receive422— Conta de destino não pode receber (encerrada/inativa).
• destination_blocked422— Chave ou conta de destino bloqueada/suspensa.

Valor e saldo

• insufficient_balance400— Saldo insuficiente para o valor + a taxa.
• amount_below_min422— Valor abaixo do mínimo permitido.
• amount_above_limit422— Valor acima do limite permitido.
• amount_unavailable422— Nenhum trilho cobre esse valor agora, tente um valor menor.
• invalid_amount422— Valor inválido ou zero.

Processamento / provedor

• duplicate422— Operação duplicada (verifique se já foi processada).
• unauthorized403— Operação não autorizada pelo provedor.
• maintenance503— Serviço em manutenção.
• provider_unavailable422— Serviço indisponível ou timeout, pode retentar.
• cashin_failed422— Falha genérica ao gerar a cobrança.
• cashout_failed422— Falha genérica no saque (consulte o suporte).

Cadastro / permissão da conta

• kyc_required403— Conta sem verificação de documentos (KYC).
• currency_not_supported400— Moeda não suportada (use BRL, MXN, ARS, COP ou USDT).
• currency_not_enabled403— Moeda não habilitada para esta conta, fale com o suporte.
• phone_required422— Telefone do comprador obrigatório no cash-in COP (NEQUI/BRE-B).

Conversão

• invalid_request400— Campos amount/from/to ausentes ou inválidos.
• conversion_failed500— Falha ao executar a conversão (nada foi debitado).
• conversion_in_progress409— Conversão com esse external_id já está em andamento, aguarde, não reenvie.

Consulta / status

• missing_reference400— Faltou o identificador (request_number / e2e / transaction_id).
• deposit_not_found404— Nenhum depósito para o identificador informado.
• withdrawal_not_found404— Nenhum saque para o identificador informado.

Exemplo de tratamento

const r = await fetch(url, opts);
const data = await r.json();
if (!data.ok) {
  switch (data.error_code) {
    case 'pix_key_not_found':
    case 'pix_key_invalid':
      // pedir outra chave ao usuário
      break;
    case 'insufficient_balance':
      // avisar saldo
      break;
    case 'provider_unavailable':
    case 'rate_limited':
      // retentar com backoff (mesmo external_id)
      break;
    default:
      // mostrar data.error e logar
  }
}