​
Resumen

Transfiya implementa un sistema de gestión de errores fundamentado en el estándar HTTP, proporcionando una estructura clara y coherente para el manejo de excepciones. Aunque los sistemas externos emplean códigos de error particulares, Transfiya ha desarrollado un mecanismo de mapeo que convierte automáticamente estos códigos a su propia arquitectura estandarizada de errores HTTP. Esta avanzada capacidad de normalización optimiza significativamente el proceso de integración para los participantes del ecosistema, minimizando o incluso eliminando por completo la necesidad de desarrollar lógicas personalizadas para el tratamiento de errores específicos.
Los errores de MOL y DICE se incluyen aquí solo con fines de referencia. El participante no necesita mapear errores de DICE directamente.

​
Mensajes de error Transfiya

Cuando se produce un error durante una transferencia o en el sistema de directorio, la plataforma responde con códigos de estado HTTP específicos y un objeto de error estructurado que proporciona información detallada sobre la incidencia. El sistema implementa una clasificación estratégica de códigos de error organizados en rangos específicos, facilitando una categorización clara, identificación rápida y resolución eficiente de incidencias. La estructura de errores está distribuida estratégicamente según el tipo de participante afectado:
  • 1xx - Errores de sistema TransfiYa
  • 3xx - Errores de participantes
El sistema Transfiya implementa un protocolo de respuesta estandarizado. Todas las solicitudes procesadas exitosamente hacia la plataforma de Minka retornan invariablemente un código de estado HTTP 200. Cuando ocurre algún error durante el procesamiento, el sistema devuelve un objeto de error estructurado que contiene un código numérico específico y una descripción clara del problema, facilitando su identificación y resolución. 
{
    "error": {
        "code": <error_code>,
        "message": "<error_message>"
    }
}
En el caso de respuestas exitosas, un objeto de error con código 0 se añade a la respuesta original.

​
Estrategia de mapeo integral

TransfiYa implementa validaciones exhaustivas de todos los campos y esquemas según los requisitos regulatorios, lo que mitiga significativamente la posibilidad de que ocurran errores de DICE. No obstante, documentamos estos mapeos de errores como medida preventiva para garantizar una respuesta adecuada ante situaciones excepcionales o imprevistas que pudieran presentarse. La estrategia general de mapeo es la siguiente:
CategoriaDescripcion
118 - ResourceValidationErrorLos errores de validación de campos
121 - ResourceNotFoundErrorLos errores relacionados con referencias inválidas, por ejemplo, ID de participante inválido
122 - DuplicateKeyLos errores por intentar ingresar registros duplicados
123 - DomainRuleViolationErrorTodas las reglas de negocio, por ejemplo, el tiempo después del cual se puede volver a utilizar una clave cancelada
136 - ApiErrorTodos los errores técnicos, por ejemplo, problemas relacionados con una configuración inválida
100 - ForbiddenErrorLos errores de seguridad

​
Alertas sobre esquemas

Por temas de interoperabilidad, Transfiya implemento modelo de advertencias o soft error validations (warrings) para habilitar entidades compatilidad el sistema actual. Eso permite que no tenemos cambios criticos en el entorno de certificacion o produccion de transfiya. Las advertencias del sistema se adhieren rigurosamente al estándar HTTP y se transmiten a través de los encabezados de error. A continuación se muestra un ejemplo representativo de una advertencia: X-Minka-Warning: 118 *labels.type* is required. This will become an error after September 2025
A partir de la entrada en operación del DICE en producción todos los participantes deben cumplir con el esquema regulatorio, de lo contratio tranfiya no procesara la petición.

​
Mapeo de Errores DICE

Sistema DICE no esta en una version estable y no se garantiza que los errores sean consistentes.
DICE y MOL se basan en el Switch ACI, que es fundamentalmente un bus de mensajes tradicional, no una solución basada en web.
Referencia para el mapeo se uso el documento Directorio Centralizado DICE Documento de Especificaciones Técnicas para la Implantación de BRE-B Dirección General de Tecnología Versión 2.2.1 2025-03-07