Manejo de errores

Toda falla de la API devuelve un cuerpo JSON estandarizado con un mensaje legible y un error_code estable. El estado HTTP también refleja el error (no siempre 200). Maneja los errores por error_code, NO cambia entre idiomas ni versiones.

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

• ok — siempre false en caso de error.
• error — mensaje legible (localizado por idioma). Bueno para mostrar/registrar; NO lo uses para lógica.
• error_code — slug estable para manejar por código (switch/if). Es la fuente de la verdad.

Estado HTTP

• 400 — solicitud inválida (datos/campos).
• 401 — credenciales ausentes o inválidas.
• 403 — sin permiso, IP no autorizada o recurso desactivado.
• 422 — dato rechazado en el procesamiento (ej.: clave no encontrada, saldo insuficiente).
• 429 — demasiados intentos. Espera e inténtalo de nuevo.
• 500 / 503 — error interno o servicio temporalmente no disponible.

Códigos de error

El mismo error_code puede aparecer en rutas distintas. Maneja siempre por el código.

Autenticación y acceso

• missing_credentials401— Client ID/Secret ausentes en la cabecera.
• invalid_credentials401— Client ID/Secret inválidos.
• key_inactive403— Clave de API inactiva.
• permission_denied403— La clave no tiene el permiso requerido (cashin/cashout/balance).
• ip_not_configured403— Cash-out sin IP en la allowlist de la clave.
• ip_not_allowed403— IP de origen fuera de la allowlist (o no IPv4).
• invalid_account403— Cuenta asociada a la clave inválida.
• rate_limited429— Demasiadas solicitudes en poco tiempo.

Clave / receptor (PIX)

• pix_key_not_found422— La clave PIX no existe en el DICT.
• pix_key_invalid422— Clave PIX con formato inválido.
• pix_key_type_invalid422— Tipo de clave no aceptado para este destino.
• invalid_document422— CPF/CNPJ inválido o no coincide con la clave.
• name_mismatch422— Nombre/documento del receptor no coincide con la clave.
• recipient_cannot_receive422— La cuenta de destino no puede recibir (cerrada/inactiva).
• destination_blocked422— Clave o cuenta de destino bloqueada/suspendida.

Monto y saldo

• insufficient_balance400— Saldo insuficiente para el monto + la tarifa.
• amount_below_min422— Monto por debajo del mínimo permitido.
• amount_above_limit422— Monto por encima del límite permitido.
• amount_unavailable422— Ningún riel cubre ese monto ahora, intenta un monto menor.
• invalid_amount422— Monto inválido o cero.

Procesamiento / proveedor

• duplicate422— Operación duplicada (verifica si ya fue procesada).
• unauthorized403— Operación no autorizada por el proveedor.
• maintenance503— Servicio en mantenimiento.
• provider_unavailable422— Servicio no disponible o timeout, puedes reintentar.
• cashin_failed422— Falla genérica al generar el cobro.
• cashout_failed422— Falla genérica en el retiro (contacta al soporte).

Cuenta / permisos

• kyc_required403— Cuenta sin verificación de documentos (KYC).
• currency_not_supported400— Moneda no soportada (usa BRL, MXN, ARS, COP o USDT).
• currency_not_enabled403— Moneda no habilitada para esta cuenta, habla con soporte.
• phone_required422— Teléfono del comprador obligatorio en el cash-in COP (NEQUI/BRE-B).

Conversión

• invalid_request400— Campos amount/from/to ausentes o inválidos.
• conversion_failed500— Falla al ejecutar la conversión (no se debitó nada).
• conversion_in_progress409— Ya hay una conversión en curso con ese external_id, espera, no reenvíes.

Consulta / estado

• missing_reference400— Faltó el identificador (request_number / e2e / transaction_id).
• deposit_not_found404— Ningún depósito para el identificador indicado.
• withdrawal_not_found404— Ningún retiro para el identificador indicado.

Ejemplo de manejo

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
  }
}