0007. Errores de dominio con un handler global y formato {"detail"}¶
Estado: Propuesto Fecha: 2026-09-29 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/core/exceptions.py, app/main.py, app/domains/*/service.py
Contexto¶
Los services detectan errores de negocio (id inexistente, código repetido,
request sin empresa) y la API debe responderlos con el código HTTP correcto.
El ADR 0005 transversal pide que el service no sepa de HTTP y que no haya
try/except repartido en los routers. Ningún ADR fija todavía un formato común
de error para la plataforma.
Decisión¶
- En
app/core/exceptions.py, una baseErrorDominio(mensaje)y una subclase por caso, cada una con sustatus_code:NoEncontrado(404),Conflicto(409),SinEmpresa(401). - El service lanza la excepción con un mensaje escrito
(
"El código X ya existe en canales comerciales"). - Un solo handler global (
registrar_manejadores_de_errores, enmain.py) la traduce a la respuesta. Los routers no usantry/exceptniHTTPException. - Formato de la respuesta: el de FastAPI,
{"detail": "mensaje"}, igual queHTTPException, core-svc-identidad y el 422 de validación.
Alternativas descartadas¶
try/except+HTTPExceptionen cada endpoint — repite la traducción en cada ruta y mete HTTP en el router.- Formato propio
{"error": {"codigo", "mensaje"}}— distinto del 422 de FastAPI y de identidad: el frontend tendría que leer dos formatos. - RFC 9457 (
application/problem+json) — es el estándar más completo, pero debe decidirse a nivel plataforma, no en un solo servicio.
Consecuencias¶
- Un error nuevo es una subclase con su
status_code; no se toca el router. - El frontend distingue el caso por el código HTTP; el
detailes texto para mostrar, no para programar contra él. - Si la plataforma adopta un formato común (por ejemplo RFC 9457), sólo cambia el handler.
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.