День 2360. #ЗаметкиНаПолях
Улучшаем Обработку Ошибок в Минимальных API с ProblemDetails
Будем честны: обработка ошибок — обычно последнее, о чём мы думаем при разработке API. Но она должна быть одной из первых.

Представьте, фронтенд вызывает API и получает в ответ следующее: "Object reference not set to an instance of an object." Вряд ли это сообщение ясно и полезно. Для сравнения:

{
  "title": "Что-то пошло не так.",
  "status": 500,
  "detail": "Пожалуйста, свяжитесь с поддержкой.",
  "instance": "/products/0"
}

Это полезно и понятно. Именно это нам и даёт ProblemDetails.

Что это?
Стандартный способ возврата сообщений об ошибках в API, определённый в RFC 7807. Вместо случайного текста или несогласованного JSON вы возвращаете структурированные ошибки, например:

{
  "title": "Product not found",
  "status": 404,
  "detail": "No product with ID 42.",
  "instance": "/products/42"
}

В ASP.NET есть встроенная поддержка ProblemDetails, и она прекрасно работает и в минимальных API. Создадим пример минимального API, который
получает продукт по ID и возвращает ошибки, используя ProblemDetails.

public record Product(int Id, string Name);
…
// получаем продукт
app.MapGet("/products/{id:int}", (int id, HttpContext http) =>
{
  var prod = context.Products
   .FirstOrDefault(p => p.Id == id);

  if (prod is null)
  {
    var notFound = new ProblemDetails
    {
      Title = "Продукт не найден",
      Status = StatusCodes.Status404NotFound,
      Detail = $"Продукт с ID={id} не найден.",
      Instance = http.Request.Path
    };

    return Results.Problem(
       title: notFound.Title,
       detail: notFound.Detail,
       statusCode: notFound.Status,
       instance: notFound.Instance
    );
  }
  return Results.Ok(prod);
});

app.Run();

Теперь запрос несуществующего продукта вернёт стандартный ответ ProblemDetails.

Дополнительные поля
Вы можете расширять ProblemDetails дополнительными данными:

public class CustomProblemDetails : ProblemDetails
{
  public string ErrorCode { get; set; } = default!;
}

Затем возвращайте его через Results.Problem(…) и передавайте дополнительные метаданные.

Преимущества
- Чистые ответы об ошибках;
- Легкость для понимания фронтендерами;
- Стандарт (RFC 7807);
- Встроено в .NET.

Глобальную обработку ошибок, начиная с .NET 8, можно настроить с помощью IExceptionHandler, который также будет выдавать ProblemDetails.

Источник: https://thecodeman.net/posts/better-error-handling-with-problemdetails