0010. Errores con un handler global y formato {"detail"}¶
Estado: Aceptado Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): app/core/exceptions.py, app/core/exceptions_handlers.py, app/main.py
Contexto¶
Los services detectan errores de negocio y la seguridad detecta errores de
autenticación, permisos o de una dependencia caída. El service no debe conocer
HTTP ni repartir try/except en los routers (ADR 0005 transversal), y
crm-svc-clientes ya fijó el formato de respuesta (su ADR 0007).
Decisión¶
app/core/exceptions.pyno importa FastAPI. Define:ErrorDominio(400) y sus subclasesNoEncontrado(404) yConflicto(409), con un mensaje escrito para el cliente.NoAutenticado(401, conWWW-Authenticate: Bearer),SinPermiso(403) yServicioNoDisponible(503), fuera de la jerarquía de dominio.- Un solo registro de handlers (
registrar_manejadores_de_errores, encreate_app). Los routers no usantry/exceptniHTTPException. - Formato:
{"detail": "mensaje"}, el de FastAPI, igual que identidad, clientes y el 422 de validación. - El 503 nunca expone el detalle técnico (URL, error de red): va al log. El 401 no dice por qué falló el token.
Alternativas descartadas¶
HTTPExceptiondesde el service — acopla el service a HTTP.- Seguridad como subclases de
ErrorDominio— no son reglas de negocio, y un handler deErrorDominiolas respondería con 400. - Un formato propio (
code,message,errors) — distinto al de los otros servicios y al de FastAPI.
Consecuencias¶
- Un caso de negocio nuevo con otro código HTTP necesita su subclase y su handler.
- El cliente no puede distinguir por código un token vencido de uno con firma inválida: ambos son 401 y se vuelve a pedir token.
Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.