How to Use Problem Details in ASP.NET Core APIs

What is Problem Details
Problem details is a format that is used for specifying errors in HTTP APIs. This format is a machine readable format that a developer can use in API responses. It can ease development and for end user, it is easier to understand the specific error. For instance, when a user tries to save any form and there is some error in between, in such case Problem Details can be helpful to throw the right error instead of telling them a 404 or 500 internal server error.

For a developer When developing HTTP APIs, it is crucial to provide consistent and informative error responses for smooth developer experience. ASP.NET Core's Problem Details is a perfect standardized solution to this challenge by ensuring your APIs communicate errors effectively and uniformly.

The objective of this standard is to make error response more informative and actionable, not just for human developers, but for the systems that consume APIs at runtime.

Problem Details Format
Problem Details contains the following.
type: A URI reference to identify the problem type. It provides human operators a place to find more information about the error.
title: A human readable summary of the problem type.
status: The HTTP status code generated on the origin of problem.
detail: A human-readable explanation specific to this occurrence of the problem.
instance: A URI reference to identifies the problem occurrence.

To get some more understanding of Problem Details let's create a sample project with Product Controller and an action method which throws an unhandled exception.

Now run your project and check the exception which will look like as follows

ASP.NET Core has built-in support for Problem Details, can be enabled by calling the AddProblemDetails method in Program.cs file. This method registers the problem details middleware to handle exceptions and return a problem details response.

We need to enable one more middleware using the UseExceptionHandler method that converts unhandled exceptions into Problem Details responses.

Let's run the API now to see the difference.

Finally call the UseStatusCodePages method to add a middleware to return a problem details response for common HTTP status codes.

Now calling any random API that does not exists we will get this response

Getting custom response using Probelm Details in ASP.Net Core
If you want to get some other information in the problem details response and want to make it to use globally, you can use ProblemDetails object like this.

Here TryHandleAsync method that will be invoked by the problem details middleware when any exception is thrown.

We have map some other exceptions such as BadHttpRequestException and UnauthorizedAccessException with appropriate HTTP status codes. We can map other specific exceptions in the same way as per our requirement.
We defined ProblemDetails object with title, status code and other details and returned in HTTP response. We have added additional information like traceId and requestId to be more informative.

Now register this custom exception handler in Program.cs file

Finally, run the API and see the results

Getting Problem Details in Web API Response
Here is the expample how you can use Problem Details in response of any Rest API

Here Problem() is a built-in method that will ingest information into ProblemDetails object and return it in response. Here is the result after running the API

Problem Details is a great way to define API exception or errors in such a way that a developer and a machine both can easily understand.