Saltar a contenido

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 base ErrorDominio(mensaje) y una subclase por caso, cada una con su status_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, en main.py) la traduce a la respuesta. Los routers no usan try/except ni HTTPException.
  • Formato de la respuesta: el de FastAPI, {"detail": "mensaje"}, igual que HTTPException, core-svc-identidad y el 422 de validación.

Alternativas descartadas

  • try/except + HTTPException en 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 detail es 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.