Translating Exceptions into Problem Details Responses

Modified October 10, 2023

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 with 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, and the catch block returns a Bad Request (Results.BadRequest()). 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

These responses are not very helpful for the consumer 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.

format_quote

Problem Details for HTTP APIs defines a "problem detail" as a way to carry machine- readable details of errors in an HTTP response to avoid the need to define new error response formats for HTTP APIs.

The Problem Details format looks like this:

 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 with 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);
builder.Services.AddProblemDetails();
 
var app = builder.Build();
app.UseStatusCodePages();
 
app.Run();

Now, when we invoke an endpoint that returns a non-successful status code, we get a Problem Details response, including a 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
}

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();

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
}

The result is already better than the default behavior, but we can 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 more 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(). The reasons why I find this better than the other options are that it's more explicit. It can also inject dependencies, short-circuit the pipeline or it can create a chain of multiple exception handlers, and the handler has access to the exception (previously you could get ahold of the exception with HttpContext.Features.Get<IExceptionHandlerFeature>()?.Error).

To write your own exception handler, you need to implement the IExceptionHandler interface, which looks as follows:

 IExceptionHandler.cs content_paste
namespace Microsoft.AspNetCore.Diagnostics;
 
public interface IExceptionHandler
{
    ValueTask<bool> TryHandleAsync(
        HttpContext httpContext,
        Exception exception,
        CancellationToken cancellationToken);
}

Your custom TryHandleAsync implementation receives the HttpContext and the Exception, 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 a possible next exception handler will be invoked.

A simple implementation of an exception handler that returns a Problem Details response based on the thrown exception could look like this.

 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 = (int)HttpStatusCode.BadRequest;
        await httpContext.Response.WriteAsJsonAsync(new ProblemDetails
        {
            Title = "An error occurred",
            Detail = exception.Message,
            Type = exception.GetType().Name,
            Status = (int)HttpStatusCode.BadRequest
        }, cancellationToken: cancellationToken);
 
        return true;
    }
}

For all exceptions that are thrown within the application, this 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 would use the exception type to return a different Problem Details response (and status code) for specific exception types.

The last step before this handler can be used 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();

When we invoke an endpoint that throws an exception, we get a Problem Details response containing more information about the exception.

 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 suffocated 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, which is available and can be used to create a Problem Details response object. The service is provided when the IServiceCollection.AddProblemDetails() method is invoked.

This means that we can refactor our exception handler to use the IProblemDetailsService service to create the Problem Details response. 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 = (int)HttpStatusCode.BadRequest;
        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.

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 on

Twitter LinkedIn