Saltar a contenido

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.py no importa FastAPI. Define:
  • ErrorDominio (400) y sus subclases NoEncontrado (404) y Conflicto (409), con un mensaje escrito para el cliente.
  • NoAutenticado (401, con WWW-Authenticate: Bearer), SinPermiso (403) y ServicioNoDisponible (503), fuera de la jerarquía de dominio.
  • Un solo registro de handlers (registrar_manejadores_de_errores, en create_app). Los routers no usan try/except ni HTTPException.
  • 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

  • HTTPException desde el service — acopla el service a HTTP.
  • Seguridad como subclases de ErrorDominio — no son reglas de negocio, y un handler de ErrorDominio las 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.