Diseñar la jerarquía de errores: dominio, técnica y frontera

Casi todos los sistemas mal diseñados en este terreno comparten un mismo síntoma: un único enum gigantesco con cuarenta casos, donde conviven el cupón caducado y el error de descodificación de JSON, y donde cada capa añade el suyo porque no había otro sitio. El resultado es predecible. La interfaz recibe fallos que no sabe explicar, el registro de incidencias pierde la causa técnica, los casos de uso capturan errores que jamás pueden ocurrir en su contexto y nadie puede añadir un caso sin romper a media docena de consumidores. La jerarquía de errores no es un detalle de higiene: es un problema de diseño de tipos con las mismas reglas que cualquier otro, y con una regla propia que lo domina todo —los errores se traducen en las fronteras, no viajan crudos.

Dos familias que no se mezclan

Un error de dominio es un desenlace previsto de una regla de negocio: saldo insuficiente, cupón caducado, plaza ya reservada. Nadie ha fallado; el sistema funciona exactamente como debía y está comunicando un resultado. Tiene sentido para la persona que usa la aplicación, suele admitir una acción correctiva y forma parte de la especificación tanto como el camino feliz.

Un fallo técnico es lo contrario: la infraestructura no cumplió. Se agotó el tiempo de espera, el servidor devolvió un cuerpo que no encaja con el modelo, el disco está lleno. No significa nada para quien usa el sistema, casi nunca admite una acción concreta más allá de reintentar, y su valor está en el diagnóstico, no en la comunicación.

Mezclarlos en un tipo produce tres daños simultáneos que conviene nombrar por separado: la interfaz acaba obligada a inventar un texto para casos que no sabe explicar; el diagnóstico se degrada porque el detalle técnico se aplana en un caso genérico; y la exhaustividad se vuelve inútil, porque cada consumidor debe considerar decenas de casos imposibles en su contexto.

// Dominio: lo entiende el negocio, tiene acción
enum ErrorDeReserva: Error {
    case sinPlazas(alternativas: [Fecha])
    case fueraDePlazo(limite: Fecha)
    case yaReservado(identificador: String)
}

// Técnico: lo entiende quien opera el sistema
enum ErrorDeTransporte: Error {
    case tiempoAgotado(segundos: Int)
    case respuestaInvalida(codigo: Int)
    case cuerpoIlegible(causa: any Error)
}

Traducir en la frontera

La regla central de esta lección es que cada capa define su propio tipo de error y traduce lo que recibe al cruzar su frontera, preservando el original como causa. Un error de descodificación no debe llegar nunca a la vista; un error de dominio no debe nacer nunca en el cliente de red.

enum ErrorDeCatalogo: Error {
    case noDisponible(referencia: String)          // dominio
    case fallaTecnica(causa: any Error)            // técnica, con la causa intacta
}

struct RepositorioDeCatalogo {
    func articulo(_ ref: String) async throws(ErrorDeCatalogo) -> Articulo {
        do {
            let dto = try await transporte.pedir(ref)
            guard dto.disponible else { throw .noDisponible(referencia: ref) }
            return Articulo(dto)
        } catch let e as ErrorDeCatalogo {
            throw e                                 // ya es del dominio: pasa
        } catch {
            throw .fallaTecnica(causa: error)       // todo lo demás se envuelve
        }
    }
}

Ese causa es lo que separa una traducción de una amputación. Al envolver conservas la cadena entera, de modo que quien registra la incidencia puede recorrerla hasta el fallo original mientras quien presenta el error solo mira el nivel superior. Perder la causa es el error más caro de todos, porque el daño no se ve hasta la madrugada en que alguien intenta diagnosticar una incidencia de producción con un mensaje que dice, íntegramente, error desconocido.

flowchart LR
T[Transporte lanza fallo tecnico] --> R[Repositorio traduce y envuelve la causa]
R --> C[Caso de uso decide reintento o dominio]
C --> V[Vista presenta mensaje y accion]
R -.causa conservada.-> L[Registro de diagnostico]
style T fill:#f38ba8,color:#11111b
style C fill:#f9e2af,color:#11111b
style V fill:#a6e3a1,color:#11111b

Dos antipatrones aparecen justo aquí. El primero es capturar y relanzar sin añadir nada: un do con un catch que solo hace throw error es ruido puro, y peor si por el camino borra el tipo. El segundo es capturar y tragar: una cláusula vacía que devuelve un valor por defecto convierte un fallo diagnosticable en un comportamiento raro que alguien investigará durante semanas.

Datos para decidir, texto para presentar

Un error bien diseñado responde a preguntas, no a la pregunta qué le digo al usuario. Esa se contesta en otra capa.

Lo que el tipo debe llevar dentro son los datos que permiten tomar una decisión: si el fallo es transitorio y merece reintento, cuánto conviene esperar, qué alternativas existen, qué identificador de correlación acompaña la incidencia. Todo eso son valores asociados, no frases.

extension ErrorDeCatalogo {
    var esTransitorio: Bool {
        if case .fallaTecnica(let causa) = self { return causa is ErrorDeTransporte }
        return false
    }
}

El texto, en cambio, pertenece a la presentación, y por tres razones que se sostienen solas: depende del idioma, depende del contexto —el mismo fallo se dice distinto en un formulario y en un panel de administración— y cambia mucho más a menudo que la lógica. Meter cadenas literales dentro del enum de dominio ata las tres cosas y hace imposible traducir sin recompilar la capa de negocio.

Cuando el sistema exige que el error sepa describirse a sí mismo, la conformidad correspondiente permite distinguir qué pasó, por qué y qué hacer, tres campos separados en lugar de una frase única. Que estén separados no es burocracia: permite que la interfaz muestre el primero en un banner, el tercero en un botón y reserve el segundo para un panel de detalle, sin volver a redactar nada.

// La traducción vive en la presentación, no en el dominio
func mensaje(para error: ErrorDeReserva) -> Mensaje {
    switch error {
    case .sinPlazas(let alternativas):
        Mensaje(texto: "No quedan plazas ese día", accion: .proponer(alternativas))
    case .fueraDePlazo(let limite):
        Mensaje(texto: "El plazo terminó el \(limite.formateada)", accion: .ninguna)
    case .yaReservado(let id):
        Mensaje(texto: "Ya tienes esta reserva", accion: .abrir(id))
    }
}

Ese switch es la prueba de fuego del diseño. Si al escribirlo descubres casos para los que no sabes redactar ninguna frase, esos casos no eran de dominio y están en el tipo equivocado. Si descubres que necesitas datos que el error no lleva, faltan valores asociados. Y si necesitas veinte ramas, el tipo abarca dos dominios distintos. Y la regla de redacción que resiste el contacto con usuarios reales cabe en tres líneas: describe lo ocurrido sin jerga, no culpes a quien lee, y ofrece siempre una siguiente acción posible aunque sea reintentar. Un código de incidencia sin acción asociada no ayuda a nadie; un código junto a una acción es exactamente lo que necesita quien atiende el soporte.

La forma del tipo y su evolución

Elegir entre enum, struct y protocolo no es estética: determina qué cambios podrás hacer sin romper a nadie.

Para código de aplicación, el enum casi siempre gana: los consumidores se recompilan a la vez y la exhaustividad es una red de seguridad real cuando el dominio crece. Para una biblioteca publicada, la balanza se inclina hacia el struct ampliable, porque cada caso nuevo dejaría de ser una mejora para convertirse en una versión mayor. Y el protocolo no compite con ninguno de los dos: sirve para expresar propiedades comunes —esto se puede reintentar, esto tiene identificador de correlación— sobre familias de errores que siguen siendo distintas.

Queda una decisión de tamaño. Un tipo de error por capa suele ser lo correcto; uno por función es ceremonia insostenible; uno por aplicación es el enum gigante del que partíamos. Si un tipo de error supera la docena de casos, casi siempre está describiendo dos dominios que aún no se han separado.