Códigos HTTP y errores

Estructura de error

Todos los errores devuelven JSON con el campo error.

{
  "error": "Insufficient balance",
  "availableBalance": 3000,
  "requiredAmount": 5200,
  "currency": "BRL"
}

Códigos HTTP

Código	Significado	Acción recomendada
400	Request inválido — campo faltante o formato incorrecto	Revisar el body del request
401	No autorizado — headers de firma incorrectos o expirados	Regenerar timestamp + nonce + firma
402	Saldo insuficiente	Verificar availableBalance en la respuesta
404	Recurso no encontrado	Verificar el txId o externalId
409	Conflicto — estado no permite la operación	Verificar el estado actual de la transacción
422	El proveedor de pagos rechazó la solicitud	Revisar los datos enviados (llave PIX inválida, etc.)
500	Error interno	Reintentar con backoff. Si persiste, contactar soporte
502	Proveedor de pagos no disponible	Reintentar en 30 segundos
503	Servicio temporalmente suspendido para esta cuenta	Contactar soporte