01
Qué es y qué problema resuelve
ProblemDetails ofrece un formato para describir errores de HTTP. El consumidor necesita un tipo o código estable y un estado coherente, no una excepción serializada.
Un traceId permite relacionar la respuesta con evidencia interna sin publicar el diagnóstico completo.
02
Ejemplo paso a paso
Punto de partida Fragmento de endpoint con HttpContext http. El conflicto es esperado; el texto no revela detalles de almacenamiento.
Antes de ejecutar
Requiere un host ASP.NET Core 10 preparado. builder y app corresponden a WebApplication.CreateBuilder y Build; las variables y tipos auxiliares deben definirse. Registra los servicios usados antes de Build. El ZIP de consola no contiene esta API.
return Results.Problem(
title: "No se pudo actualizar la reserva",
statusCode: 409,
extensions: new Dictionary<string, object?>
{
["codigo"] = "version_obsoleta",
["traceId"] = http.TraceIdentifier
});Cómo funciona
- Identifica el estado HTTP y el significado del conflicto.
- Lee el título y los datos seguros que recibirá el consumidor.
- Usa traceId para relacionar la respuesta con el diagnóstico interno.
Resultado esperado: 409 y un cuerpo ProblemDetails con código estable y correlación.
03
Cuándo usarlo y qué debes evitar
El detalle debe ser seguro y útil: nombre de campo y regla incumplida para entrada, código de conflicto para estado y mensaje genérico para fallo inesperado. No incluyas SQL, rutas locales, tokens o cookies.
La respuesta debe mantener content type, código y cuerpo consistentes; no devuelvas 200 con un campo error para simular éxito.
Ampliación opcional · contexto y variantes del tema
ProblemDetails y errores con significado
Una respuesta de error consistente incluye tipo, título, estado y un identificador de correlación. El detalle debe ayudar al consumidor sin revelar SQL, nombres internos, rutas locales ni credenciales. Para fallos inesperados devuelve un mensaje genérico y conserva el diagnóstico en un registro protegido. Para conflictos esperados ofrece un código estable que el cliente pueda interpretar sin analizar una frase.
AddProblemDetails registra servicios; UseExceptionHandler intercepta fallos del pipeline. No confundas configurarlos con capturar toda excepción dentro de cada caso de uso. Una cancelación solicitada por el cliente no es automáticamente un 500. En .NET 10, un IExceptionHandler que devuelve true suprime por defecto ciertos diagnósticos de excepciones atendidas: revisa SuppressDiagnosticsCallback o registra explícitamente lo que necesitas sin duplicarlo.
Punto de partida Coloca el manejo de errores antes de componentes susceptibles de fallar. Este fragmento no añade un IExceptionHandler propio: usa la respuesta ProblemDetails predeterminada y agrega correlación.
Antes de ejecutar
Configuración ASP.NET Core 10
builder.Services.AddProblemDetails(opciones =>
{
opciones.CustomizeProblemDetails = contexto =>
contexto.ProblemDetails.Extensions["traceId"] =
contexto.HttpContext.TraceIdentifier;
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();Resultado esperado: Errores compatibles pueden incluir traceId; la respuesta no expone la excepción original.
04 · Práctica guiada · opcional
Practica lo aprendido
Diseña cuerpo para entrada inválida, conflicto y fallo interno.
- 01Prepara el ejemplo con las dependencias indicadas en «Antes de ejecutar».
- 02Diseña cuerpo para entrada inválida, conflicto y fallo interno.
- 03Comprueba y registra el resultado: 409 y un cuerpo ProblemDetails con código estable y correlación.
Ver solución orientativa
Mantén estados distintos y prueba que el 500 no contiene excepciones. El consumidor usa códigos, no analiza frases humanas.
05
Comprueba lo aprendido
Responde antes de abrir la explicación. Esta comprobación es opcional y no guarda una puntuación.
01¿ProblemDetails decide cuándo autorizar?
No. Es representación del error; los controles ocurren antes.
02¿Qué dato debe usar el portal para reconocer el conflicto sin depender de la frase del título?
Usa el código estable version_obsoleta y el estado 409. El título puede cambiar o traducirse; traceId sirve para correlacionar diagnóstico, no para clasificar el conflicto.
Cómo demostrar el objetivo
Compara tu práctica con estos resultados. Si solo diseñaste una prueba, registra su resultado como esperado, no como observado.
- El conflicto usa 409 y un código estable version_obsoleta.
- El diseño de 500 conserva correlación y omite excepciones y detalles internos.
Qué debes recordar
- El error público debe ser estable y comprensible.
- La correlación permite investigar sin publicar el diagnóstico.
Tu cuaderno · notas personales
Cuaderno local
Tus notas del contenido
Se guardan únicamente en este dispositivo. Puedes exportarlas cuando quieras.
Material de apoyo · descarga, glosario y referencias
Explicaciones, ejemplos y prácticas propios de Academia de Software. Los fragmentos de integración requieren las dependencias indicadas; el ZIP contiene el núcleo de consola. Las lecturas externas se consultan en su sitio original y conservan sus condiciones. Procedencia y condiciones de uso.