Translating Exceptions into Problem Details Responses

Modified September 26, 2024

Tim Deschryver

timdeschryver.dev

Because (ASP).NET 8 is in preview it doesn't mean we can't start trying out some of the new features. In this post, we'll take a look at the new IExceptionHandler interface, which is introduced in Preview 5, to turn exceptions into Problem Details.

• Default API behavior
• Problem Details
• Problem Details in ASP.NET
• Exception Handler
  • Exception Handler using IProblemDetailsService
  • Default Problem Detail Extensions
• Conclusion

Default API behavior link

Before we start introducing problem details and the exception handler, let's refresh our memory on how ASP.NET Core handles exceptions by default. An important detail to note is that the default behavior is different between development and production environments. Throughout this post, I'm only going to focus on the production environment.

When an endpoint is invoked and an exception is thrown while the request is being processed, the endpoint returns a 500 Internal Server Error response.

 content_paste
HTTP/1.1 500 Internal Server Error
Content-Length: 0
Connection: close
Date: Mon, 24 Jul 2023 13:52:12 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400

This is different when the exception is caught, and handled by the developer. An example of this is that the logic within the endpoint is wrapped in a try-catch block, which returns a Bad Request (Results.BadRequest()) when an exception is catched. This results in a 400 Bad Request response.

 content_paste
HTTP/1.1 400 Bad Request
Content-Length: 0
Connection: close
Date: Mon, 24 Jul 2023 14:08:16 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400

While we understand what's happening, the response doesn't provide any information about the error. This isn't very helpful to the consumer(s) of the API.

Problem Details link

Problem Details is a described format for returning error information in HTTP API responses. While it's still in the "Proposed Standard" status, it's already widely used in the industry and built into ASP.NET Core.

The Problem Details format looks as follows:

 problem-details.json content_paste
{
    "type": "(string) - A URI reference [RFC3986] that identifies the
      problem type.  This specification encourages that, when
      dereferenced, it provides human-readable documentation for the
      problem type (e.g., using HTML [W3C.REC-html5-20141028]).  When
      this member is not present, its value is assumed to be
      'about:blank'",
    "title": "(string) - A short, human-readable summary of the problem
      type.  It SHOULD NOT change from occurrence to occurrence of the
      problem, except for purposes of localization (e.g., using
      proactive content negotiation; see [RFC7231], Section 3.4).",
    "status": "(number) - The HTTP status code ([RFC7231], Section 6)
      generated by the origin server for this occurrence of the problem.",
    "detail": "(string) - A human-readable explanation specific to this
      occurrence of the problem.",
    "instance": "(string) - A URI reference that identifies the specific
      occurrence of the problem.  It may or may not yield further
      information if dereferenced.",
}

Besides the described format, this object can also be extended with additional members to provide more information, these are called Extension Members.

Problem Details in ASP.NET link

ASP.NET Core already has built-in support for Problem Details. To enable it, you need to invoke the IServiceCollection.AddProblemDetails() extension method and the IApplicationBuilder.UseStatusCodePages() extension method.

 Program.cs content_paste
var builder = WebApplication.CreateBuilder(args);
// Return the Problem Details format for non-successful responses
builder.Services.AddProblemDetails();
 
var app = builder.Build();
// Return the body of the response when the status code is not successful
// (the default behavior is to return an empty body with a Status Code)
app.UseStatusCodePages();
 
app.Run();

Now, when we invoke an endpoint that returns a non-successful status code, we get to see a Problem Details response, including a helpful response body.

 9-13} content_paste
HTTP/1.1 400 Bad Request
Connection: close
Content-Type: application/problem+json
Date: Mon, 24 Jul 2023 14:32:04 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400
Transfer-Encoding: chunked
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400
}

This only works for status codes that are returned by the application. To have the same behavior for exceptions, you also need to call the IApplicationBuilder.UseExceptionHandler() extension method.

 Program.cs content_paste
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
 
var app = builder.Build();
app.UseStatusCodePages();
app.UseExceptionHandler();
 
app.Run();

This will translate the unhandled exception into a Problem Detail, and returns a 500 Internal Server Error response. Resulting in the following response when the application throws an unhandled exception.

 12-16} content_paste
HTTP/1.1 500 Internal Server Error
Connection: close
Content-Type: application/problem+json
Date: Mon, 24 Jul 2023 14:36:41 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400
Cache-Control: no-cache,no-store
Expires: -1
Pragma: no-cache
Transfer-Encoding: chunked
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.6.1",
  "title": "An error occurred while processing your request.",
  "status": 500
}

We already have something better than the default behavior, but we can further improve this.

Exception Handler link

Before the addition of IExceptionHandler exception handler, we could make use of a Exception Handler Page or a Exception Handler Lambda. Both of these options are still available, but the new IExceptionHandler interface provides a clean and flexible way of handling exceptions in my opinion.

An exception handler is a class that implements the IExceptionHandler interface, and is registered by using IServiceCollection.AddExceptionHandler() to the DI container.

The reasons why I find this better than the other options are that it's more explicit. It also provides more features such as injecting dependencies, short-circuiting the pipeline, and it can add multiple exception handlers to the middleware pipeline. Lastly, our handler receives the exception, which makes it easy to write logic based on it. This was also possible before, but to get ahold of the exception you had to grab the exception from the IExceptionHandlerFeature feature using HttpContext.Features.Get<IExceptionHandlerFeature>()?.Error.

To write your own exception handler, create a new class that implements the IExceptionHandler interface.

Your IExceptionHandler implementation receives the HttpContext and the Exception as arguments in the TryHandleAsync method that you need to implement, and needs to return a ValueTask<bool>. If the handler returns true, the exception is considered handled, and the request pipeline is short-circuited. When the value false is returned, the default flow continues and the next middleware in the pipeline is invoked.

A simple exception handler that returns a Problem Details response based on the thrown exception has the following implementation.

 ExceptionToProblemDetailsHandler.cs content_paste
public class ExceptionToProblemDetailsHandler : Microsoft.AspNetCore.Diagnostics.IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Title = "An error occurred",
            Detail = exception.Message,
            Type = exception.GetType().Name,
            Status = StatusCodes.Status400BadRequest
        }, cancellationToken: cancellationToken);
 
        return true;
    }
}

For all exceptions that are thrown within the application, the above handler will be invoked.

Let's go over it to see what it does. The handler sets the HTTP response status code, and creates and writes a Problem Details response object directly to the response using the information from the exception.

A more advanced implementation could use the exception type to return a different Problem Details response (including a different status code).

The last step is to register the exception handler using the IServiceCollection.AddExceptionHandler() extension method.

 Program.cs content_paste
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<ExceptionToProblemDetailsHandler>();
 
var app = builder.Build();
app.UseStatusCodePages();
app.UseExceptionHandler();
 
app.Run();

Now when an exception is thrown from an endpoint, we get a Problem Details response containing more information about the exception. This is because we append the exception message to the response as the detail of the Problem Details object.

 txt content_paste
HTTP/1.1 400 Bad Request
Connection: close
Content-Type: application/json; charset=utf-8
Date: Mon, 24 Jul 2023 16:15:50 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400
Cache-Control: no-cache,no-store
Expires: -1
Pragma: no-cache
Transfer-Encoding: chunked
{
  "type": "ArgumentException",
  "title": "An error occurred",
  "status": 400,
  "detail": "Id must be greater than zero (Parameter 'id')"
}

Exception Handler using IProblemDetailsService link

In the previous example, we created a Problem Details response manually. While this works, there's a more sophisticated solution available to return a Problem Details response.

Do you remember that I mentioned that ASP.NET has built-in support for Problem Details?

It doesn't only mean that problem details are returned for non-successful responses, nor does it mean that the ProblemDetails class exists in the framework. It also means that there's the IProblemDetailsService service to our availability, which creates a Problem Details response object more easily.

Keep in mind that the IProblemDetailsService service is available (and can be injected) because the IServiceCollection.AddProblemDetails() method is invoked, which registers the service to the DI container.

This means that we can use this to refactor our exception handler to use the IProblemDetailsService service! Instead of manually creating the problem details, we can do this by taking advantage of the service. The cleaned-up version of the exception handler looks like this.

 ExceptionToProblemDetailsHandler.cs content_paste
public class ExceptionToProblemDetailsHandler: Microsoft.AspNetCore.Diagnostics.IExceptionHandler
{
    private readonly IProblemDetailsService _problemDetailsService;
 
    public ExceptionToProblemDetailsHandler(IProblemDetailsService problemDetailsService)
    {
        _problemDetailsService = problemDetailsService;
    }
 
    public async ValueTask<bool> TryHandleAsync(HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        httpContext.Response.StatusCode = StatusCodes.Status400BadRequest;
        return await _problemDetailsService.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            ProblemDetails =
                {
                    Title = "An error occurred",
                    Detail = exception.Message,
                    Type = exception.GetType().Name,
                },
            Exception = exception
        });
    }
}

After this change, the response is still the same as before.

 txt content_paste
HTTP/1.1 400 Bad Request
Connection: close
Content-Type: application/problem+json
Date: Mon, 24 Jul 2023 16:28:38 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400
Cache-Control: no-cache,no-store
Expires: -1
Pragma: no-cache
Transfer-Encoding: chunked
{
  "type": "ArgumentException",
  "title": "An error occurred",
  "status": 400,
  "detail": "Id must be greater than zero (Parameter 'id')"
}

But, if you have a sharp eye, you might have noticed several small differences. Because we use the IProblemDetailsService service:

• the content type is now application/problem+json instead of application/json;
• we're not required to set the Status property on the ProblemDetails instance because the IProblemDetailsService service will set it for us using the status code of the response;

Default Problem Detail Extensions link

I also mentioned that problem details can be extended with additional properties. One way of doing this is by providing these members during the instantiation of the ProblemDetails instance. But, we can also configure the IProblemDetailsService service to add default properties that we want to add to every Problem Details response.

For this, we can use the overload of the AddProblemDetails() method. In the example below, we add the trace identifier and the instance (the endpoint that is invoked) to the Problem Details response.

 Program.cs content_paste
var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddProblemDetails(options =>
        options.CustomizeProblemDetails = ctx =>
        {
            ctx.ProblemDetails.Extensions.Add("trace-id", ctx.HttpContext.TraceIdentifier);
            ctx.ProblemDetails.Extensions.Add("instance", $"{ctx.HttpContext.Request.Method} {ctx.HttpContext.Request.Path}");
        });
builder.Services.AddExceptionHandler<ExceptionToProblemDetailsHandler>();
 
var app = builder.Build();
app.UseStatusCodePages();
app.UseExceptionHandler();
 
app.Run();

Resulting in the following response object when an exception is thrown.

 txt content_paste
HTTP/1.1 400 Bad Request
Connection: close
Content-Type: application/problem+json
Date: Mon, 24 Jul 2023 17:08:52 GMT
Server: Kestrel
Alt-Svc: h3=":5099"; ma=86400
Cache-Control: no-cache,no-store
Expires: -1
Pragma: no-cache
Transfer-Encoding: chunked
{
  "type": "ArgumentException",
  "title": "An error occurred",
  "status": 400,
  "detail": "Id must be greater than zero (Parameter 'id')",
  "trace-id": "0HMSCD2K3EJLN:00000001",
  "instance": "GET /users/-5"
}

Conclusion link

In this post, I implemented the ExceptionToProblemDetailsHandler class that implements the newly introduced IExceptionHandler interface in ASP.NET Core 8. The exception handler uses the Problem Details Service to translate thrown exceptions into Problem Details response objects.

The result is a standardized and better experience for your API consumers when the request is invalid, or when something went wrong during the processing of the request.

Incoming links

• Taking a look at the Problem Details enhancements in ASP.NET 9

Feel free to update this blog post on GitHub, thanks in advance!

Support me

I appreciate it if you would support me if have you enjoyed this post and found it useful, thank you in advance.

Share this post

Twitter LinkedIn