Mi Wiki Técnica

Appearance

Guía rápida de errores HTTP en ASP.NET Core ​

1. ¿Cómo devuelvo un error? ​

En un controlador que hereda de ControllerBase, puedes devolver respuestas HTTP con métodos como BadRequest(), NotFound() y Conflict().

Puedes incluir un mensaje para explicar qué ocurrió:

csharp
return NotFound($"Producto con ID {id} no encontrado");

El mensaje ayuda al cliente a comprender por qué falló la operación.

2. Errores HTTP comunes ​

MétodoCódigo¿Cuándo usarlo?
BadRequest()400Los datos enviados son inválidos o incumplen una regla de la operación.
Unauthorized()401Falta autenticación válida.
Forbid()403El usuario no tiene permiso para realizar la operación.
NotFound()404El recurso solicitado no existe.
Conflict()409La operación entra en conflicto con el estado actual del recurso.
StatusCode(500)500Ocurrió un error interno del servidor.

3. Ejemplos prácticos ​

NotFound() — El recurso no existe ​

csharp
var producto = await _context.Productos.FindAsync(id);

if (producto == null)
{
    return NotFound($"Producto con ID {id} no encontrado");
}

Se utiliza cuando intentas buscar un producto y no existe en la base de datos.

BadRequest() — Los datos son inválidos ​

csharp
if (linea.Cantidad <= 0)
{
    return BadRequest(
        $"La cantidad para el producto {producto.Nombre} debe ser mayor que cero"
    );
}

Se utiliza cuando el producto existe, pero los datos de la solicitud incumplen una regla de negocio.

Otro ejemplo:

csharp
if (linea.Descuento < 0)
{
    return BadRequest("El descuento no puede ser negativo");
}

Conflict() — Existe un conflicto con el estado actual ​

csharp
if (producto.Stock < linea.Cantidad)
{
    return Conflict("No hay suficiente inventario para completar el pedido");
}

Se puede utilizar cuando el pedido solicita más unidades de las disponibles.

Unauthorized() — Falta autenticación ​

csharp
return Unauthorized();

Se utiliza cuando la solicitud no cuenta con autenticación válida. En una API con [Authorize], ASP.NET Core normalmente gestiona este caso automáticamente.

Forbid() — No hay permisos suficientes ​

csharp
return Forbid();

Se utiliza cuando el usuario está autenticado, pero no tiene autorización para ejecutar la operación.

4. ¿Cómo elegir entre 400 y 404? ​

La diferencia fundamental es qué está fallando:

  • 404: no existe el recurso que intentas encontrar.
  • 400: el recurso puede existir, pero los datos enviados no son válidos para la operación.

Por ejemplo, al calcular un pedido:

csharp
var producto = await _context.Productos.FindAsync(linea.ProductoId);

if (producto == null)
{
    return NotFound("El producto solicitado no existe");
}

if (linea.Cantidad <= 0)
{
    return BadRequest("La cantidad debe ser mayor que cero");
}

Primero verificas que exista el producto; después validas los datos de la línea.

5. Reglas prácticas ​

  • Devuelve el código HTTP que mejor represente lo ocurrido.
  • Incluye mensajes claros y útiles para el cliente.
  • No devuelvas contraseñas, datos sensibles, trazas de errores ni detalles internos de la base de datos.
  • No uses 500 Internal Server Error para errores esperables, como un producto inexistente o una cantidad inválida.
  • Recuerda que devolver un error no corrige la situación: detiene el flujo de la acción y comunica el problema al cliente.

Regla para recordar ​

404: no encontré el recurso.
400: los datos no son válidos.
401: falta autenticación válida.
403: no tienes permiso.
409: existe un conflicto con el estado actual.
500: ocurrió un error inesperado en el servidor.