Cómo manejar errores globales en una API ASP.NET Core

Antes o después de desarrollar una API en ASP.NET Core, todos los proyectos se enfrentan al mismo desafío: manejar errores de forma consistente. Cuando cada controlador devuelve mensajes distintos o expone información técnica al cliente, la API se vuelve difícil de mantener y poco profesional. La solución consiste en implementar un manejo global de excepciones que centralice la captura de errores y entregue respuestas uniformes.

En este artículo aprenderás cómo manejar errores globales en una API ASP.NET Core utilizando las herramientas integradas del framework y siguiendo buenas prácticas para aplicaciones modernas.

¿Por qué implementar un manejo global de errores?

Muchos desarrolladores comienzan utilizando bloques try-catch en cada método del controlador. Aunque funciona para casos pequeños, rápidamente aparecen problemas:

• Código repetitivo.
• Difícil mantenimiento.
• Respuestas inconsistentes.
• Riesgo de mostrar información sensible.
• Mayor probabilidad de olvidar capturar excepciones.

Un middleware de manejo global evita estos inconvenientes capturando cualquier excepción no controlada antes de que la respuesta llegue al cliente.

El enfoque recomendado en ASP.NET Core

ASP.NET Core permite interceptar todas las excepciones mediante middleware. Este componente se ejecuta dentro del pipeline HTTP y puede:

• Registrar el error.
• Determinar el código HTTP adecuado.
• Crear una respuesta JSON uniforme.
• Ocultar detalles internos de la aplicación.

De esta forma todos los consumidores de la API reciben el mismo formato de respuesta independientemente del lugar donde ocurrió el error.

Crear un middleware de excepciones

Una implementación básica puede comenzar creando una clase denominada:

public class ExceptionMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<ExceptionMiddleware> _logger;

    public ExceptionMiddleware(
        RequestDelegate next,
        ILogger<ExceptionMiddleware> logger)
    {
        _next = next;
        _logger = logger;
    }

    public async Task Invoke(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, ex.Message);

            context.Response.StatusCode = 500;
            context.Response.ContentType = "application/json";

            var response = new
            {
                Success = false,
                Message = "Ha ocurrido un error interno."
            };

            await context.Response.WriteAsJsonAsync(response);
        }
    }
}

Este middleware captura cualquier excepción no controlada, registra el error utilizando ILogger y devuelve una respuesta JSON limpia.

Registrar el middleware

En Program.cs basta con agregar:

app.UseMiddleware<ExceptionMiddleware>();

Es recomendable registrarlo al inicio del pipeline para interceptar cualquier excepción generada posteriormente.

Personalizar los códigos HTTP

No todos los errores representan un problema interno del servidor. Una buena práctica consiste en traducir determinadas excepciones a códigos HTTP apropiados.

Por ejemplo:

• 400 Bad Request para datos inválidos.
• 401 Unauthorized cuando falta autenticación.
• 403 Forbidden cuando no existen permisos.
• 404 Not Found cuando el recurso no existe.
• 409 Conflict para conflictos de negocio.
• 500 Internal Server Error para errores inesperados.

Esto permite que los consumidores interpreten correctamente cada situación.

Utilizar ProblemDetails

Desde ASP.NET Core existe el estándar ProblemDetails, basado en la especificación RFC 7807. Este formato proporciona respuestas estructuradas para los errores e incluye información como:

• Tipo del problema.
• Título.
• Código HTTP.
• Descripción.
• Ruta solicitada.

Adoptar este estándar facilita la integración con aplicaciones web, móviles y herramientas como Swagger.

Registrar información sin exponerla

Uno de los errores más comunes es devolver el mensaje completo de la excepción al cliente.

Por ejemplo, respuestas como:

SqlException:
Connection failed...

representan un riesgo de seguridad.

Lo recomendable es:

• Registrar toda la excepción en los logs.
• Mostrar al usuario un mensaje genérico.
• Generar un identificador de seguimiento (TraceId).
• Consultar los detalles únicamente desde el sistema de registros.

Integración con sistemas de logging

El middleware global funciona perfectamente con herramientas como:

• Serilog.
• NLog.
• Seq.
• Azure Application Insights.
• Elastic Stack.

De esta manera cada excepción queda almacenada con información como usuario, fecha, endpoint, tiempo de ejecución y stack trace para facilitar el diagnóstico.

Buenas prácticas

Para un manejo profesional de errores en ASP.NET Core se recomienda:

• Centralizar todas las excepciones en un middleware.
• Evitar bloques try-catch innecesarios en los controladores.
• Utilizar respuestas JSON consistentes.
• Registrar todos los errores mediante un sistema de logging.
• No revelar información interna al cliente.
• Utilizar códigos HTTP adecuados.
• Considerar el uso de ProblemDetails como formato estándar.

Implementar un manejo global de errores en una API ASP.NET Core mejora significativamente la calidad del proyecto. Centralizar las excepciones reduce código repetitivo, facilita el mantenimiento y proporciona respuestas consistentes para todos los consumidores de la API. Combinado con un buen sistema de logging y el uso de estándares como ProblemDetails, se obtiene una aplicación más robusta, segura y preparada para entornos de producción.