Handle errors in ASP.NET Core controller-based web APIs

This article describes how to handle errors and customize error handling in controller-based ASP.NET Core web APIs. For information about error handling in minimal APIs, see Handle errors in ASP.NET Core and Handle errors in minimal APIs.

Developer Exception Page

The Developer Exception Page displays detailed information about unhandled request exceptions. It uses DeveloperExceptionPageMiddleware to capture synchronous and asynchronous exceptions from the HTTP pipeline and to generate error responses. The developer exception page runs early in the middleware pipeline, so that it can catch unhandled exceptions thrown in middleware that follows.

ASP.NET Core apps enable the developer exception page by default when both:

• Running in the Development environment.
• The app was created with the current templates, that is, by using WebApplication.CreateBuilder.

Apps created using earlier templates, that is, by using WebHost.CreateDefaultBuilder, can enable the developer exception page by calling app.UseDeveloperExceptionPage.

Warning

Don't enable the Developer Exception Page unless the app is running in the Development environment. Don't share detailed exception information publicly when the app runs in production. For more information on configuring environments, see Use multiple environments in ASP.NET Core.

The Developer Exception Page can include the following information about the exception and the request:

• Stack trace
• Query string parameters, if any
• Cookies, if any
• Headers
• Endpoint metadata, if any

The Developer Exception Page isn't guaranteed to provide any information. Use Logging for complete error information.

The following image shows a sample developer exception page with animation to show the tabs and the information displayed:

In response to a request with an Accept: text/plain header, the Developer Exception Page returns plain text instead of HTML. For example:

Status: 500 Internal Server Error
Time: 9.39 msSize: 480 bytes
FormattedRawHeadersRequest
Body
text/plain; charset=utf-8, 480 bytes
System.InvalidOperationException: Sample Exception
   at WebApplicationMinimal.Program.<>c.<Main>b__0_0() in C:\Source\WebApplicationMinimal\Program.cs:line 12
   at lambda_method1(Closure, Object, HttpContext)
   at Microsoft.AspNetCore.Diagnostics.DeveloperExceptionPageMiddlewareImpl.Invoke(HttpContext context)

HEADERS
=======
Accept: text/plain
Host: localhost:7267
traceparent: 00-0eab195ea19d07b90a46cd7d6bf2f

To see the Developer Exception Page:

• Add the following controller action to a controller-based API. The action throws an exception when the endpoint is requested.

  [HttpGet("Throw")]
  public IActionResult Throw() =>
      throw new Exception("Sample exception.");
  

• Run the app in the development environment.

• Go to the endpoint defined by the controller action.

Exception handler

In non-development environments, use Exception Handling Middleware to produce an error payload:

1. In Program.cs, call UseExceptionHandler to add the Exception Handling Middleware:

   var app = builder.Build();
   
   app.UseHttpsRedirection();
   
   if (!app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error");
   }
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

2. Configure a controller action to respond to the /error route:

   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

The preceding HandleError action sends an RFC 7807-compliant payload to the client.

Warning

Don't mark the error handler action method with HTTP method attributes, such as HttpGet. Explicit verbs prevent some requests from reaching the action method.

For web APIs that use Swagger / OpenAPI, mark the error handler action with the [ApiExplorerSettings] attribute and set its IgnoreApi property to true. This attribute configuration excludes the error handler action from the app's OpenAPI specification:

[ApiExplorerSettings(IgnoreApi = true)]

Allow anonymous access to the method if unauthenticated users should see the error.

Exception Handling Middleware can also be used in the Development environment to produce a consistent payload format across all environments:

1. In Program.cs, register environment-specific Exception Handling Middleware instances:

   if (app.Environment.IsDevelopment())
   {
       app.UseExceptionHandler("/error-development");
   }
   else
   {
       app.UseExceptionHandler("/error");
   }
   

   In the preceding code, the middleware is registered with:

   • A route of /error-development in the Development environment.
   • A route of /error in non-Development environments.

2. Add controller actions for both the Development and non-Development routes:

   [Route("/error-development")]
   public IActionResult HandleErrorDevelopment(
       [FromServices] IHostEnvironment hostEnvironment)
   {
       if (!hostEnvironment.IsDevelopment())
       {
           return NotFound();
       }
   
       var exceptionHandlerFeature =
           HttpContext.Features.Get<IExceptionHandlerFeature>()!;
   
       return Problem(
           detail: exceptionHandlerFeature.Error.StackTrace,
           title: exceptionHandlerFeature.Error.Message);
   }
   
   [Route("/error")]
   public IActionResult HandleError() =>
       Problem();
   

Use exceptions to modify the response

The contents of the response can be modified from outside of the controller using a custom exception and an action filter:

1. Create a well-known exception type named HttpResponseException:

   public class HttpResponseException : Exception
   {
       public HttpResponseException(int statusCode, object? value = null) =>
           (StatusCode, Value) = (statusCode, value);
   
       public int StatusCode { get; }
   
       public object? Value { get; }
   }
   

2. Create an action filter named HttpResponseExceptionFilter:

   public class HttpResponseExceptionFilter : IActionFilter, IOrderedFilter
   {
       public int Order => int.MaxValue - 10;
   
       public void OnActionExecuting(ActionExecutingContext context) { }
   
       public void OnActionExecuted(ActionExecutedContext context)
       {
           if (context.Exception is HttpResponseException httpResponseException)
           {
               context.Result = new ObjectResult(httpResponseException.Value)
               {
                   StatusCode = httpResponseException.StatusCode
               };
   
               context.ExceptionHandled = true;
           }
       }
   }
   

   The preceding filter specifies an Order of the maximum integer value minus 10. This Order allows other filters to run at the end of the pipeline.

3. In Program.cs, add the action filter to the filters collection:

   builder.Services.AddControllers(options =>
   {
       options.Filters.Add<HttpResponseExceptionFilter>();
   });
   

Validation failure error response

For web API controllers, MVC responds with a ValidationProblemDetails response type when model validation fails. MVC uses the results of InvalidModelStateResponseFactory to construct the error response for a validation failure. The following example replaces the default factory with an implementation that also supports formatting responses as XML, in Program.cs:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.InvalidModelStateResponseFactory = context =>
            new BadRequestObjectResult(context.ModelState)
            {
                ContentTypes =
                {
                    // using static System.Net.Mime.MediaTypeNames;
                    Application.Json,
                    Application.Xml
                }
            };
    })
    .AddXmlSerializerFormatters();

Client error response

An error result is defined as a result with an HTTP status code of 400 or higher. For web API controllers, MVC transforms an error result to produce a ProblemDetails.

The automatic creation of a ProblemDetails for error status codes is enabled by default, but error responses can be configured in one of the following ways:

1. Use the problem details service
2. Implement ProblemDetailsFactory
3. Use ApiBehaviorOptions.ClientErrorMapping

Default problem details response

The following Program.cs file was generated by the web application templates for API controllers:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Consider the following controller, which returns BadRequest when the input is invalid:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

A problem details response is generated with the preceding code when any of the following conditions apply:

• The /api/values2/divide endpoint is called with a zero denominator.
• The /api/values2/squareroot endpoint is called with a radicand less than zero.

The default problem details response body has the following type, title, and status values:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "traceId": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00"
}

Problem details service

ASP.NET Core supports creating Problem Details for HTTP APIs using the IProblemDetailsService. For more information, see the Problem details service.

The following code configures the app to generate a problem details response for all HTTP client and server error responses that don't have body content yet:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.MapControllers();
app.Run();

Consider the API controller from the preceding section, which returns BadRequest when the input is invalid:

[Route("api/[controller]/[action]")]
[ApiController]
public class Values2Controller : ControllerBase
{
    // /api/values2/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values2 /squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }
}

A problem details response is generated with the preceding code when any of the following conditions apply:

• An invalid input is supplied.
• The URI has no matching endpoint.
• An unhandled exception occurs.

The automatic creation of a ProblemDetails for error status codes is disabled when the SuppressMapClientErrors property is set to true:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.SuppressMapClientErrors = true;
    });

var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Using the preceding code, when an API controller returns BadRequest, an HTTP 400 response status is returned with no response body. SuppressMapClientErrors prevents a ProblemDetails response from being created, even when calling WriteAsync for an API Controller endpoint. WriteAsync is explained later in this article.

The next section shows how to customize the problem details response body, using CustomizeProblemDetails, to return a more helpful response. For more customization options, see Customizing problem details.

Customize problem details with CustomizeProblemDetails

The following code uses ProblemDetailsOptions to set CustomizeProblemDetails:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddProblemDetails(options =>
        options.CustomizeProblemDetails = (context) =>
        {

            var mathErrorFeature = context.HttpContext.Features
                                                       .Get<MathErrorFeature>();
            if (mathErrorFeature is not null)
            {
                (string Detail, string Type) details = mathErrorFeature.MathError switch
                {
                    MathErrorType.DivisionByZeroError =>
                    ("Divison by zero is not defined.",
                                          "https://wikipedia.org/wiki/Division_by_zero"),
                    _ => ("Negative or complex numbers are not valid input.",
                                          "https://wikipedia.org/wiki/Square_root")
                };

                context.ProblemDetails.Type = details.Type;
                context.ProblemDetails.Title = "Bad Input";
                context.ProblemDetails.Detail = details.Detail;
            }
        }
    );

var app = builder.Build();

app.UseHttpsRedirection();

app.UseStatusCodePages();

app.UseAuthorization();

app.MapControllers();

app.Run();

The updated API controller:

[Route("api/[controller]/[action]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // /api/values/divide/1/2
    [HttpGet("{Numerator}/{Denominator}")]
    public IActionResult Divide(double Numerator, double Denominator)
    {
        if (Denominator == 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.DivisionByZeroError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Numerator / Denominator);
    }

    // /api/values/squareroot/4
    [HttpGet("{radicand}")]
    public IActionResult Squareroot(double radicand)
    {
        if (radicand < 0)
        {
            var errorType = new MathErrorFeature
            {
                MathError = MathErrorType.NegativeRadicandError
            };
            HttpContext.Features.Set(errorType);
            return BadRequest();
        }

        return Ok(Math.Sqrt(radicand));
    }

}

The following code contains the MathErrorFeature and MathErrorType, which are used with the preceding sample:

// Custom Http Request Feature
class MathErrorFeature
{
    public MathErrorType MathError { get; set; }
}

// Custom math errors
enum MathErrorType
{
    DivisionByZeroError,
    NegativeRadicandError
}

A problem details response is generated with the preceding code when any of the following conditions apply:

• The /divide endpoint is called with a zero denominator.
• The /squareroot endpoint is called with a radicand less than zero.
• The URI has no matching endpoint.

The problem details response body contains the following when either squareroot endpoint is called with a radicand less than zero:

{
  "type": "https://en.wikipedia.org/wiki/Square_root",
  "title": "Bad Input",
  "status": 400,
  "detail": "Negative or complex numbers are not allowed."
}

View or download sample code

Implement ProblemDetailsFactory

MVC uses Microsoft.AspNetCore.Mvc.Infrastructure.ProblemDetailsFactory to produce all instances of ProblemDetails and ValidationProblemDetails. This factory is used for:

• Client error responses
• Validation failure error responses
• ControllerBase.Problem and ControllerBase.ValidationProblem

To customize the problem details response, register a custom implementation of ProblemDetailsFactory in Program.cs:

builder.Services.AddControllers();
builder.Services.AddTransient<ProblemDetailsFactory, SampleProblemDetailsFactory>();

Use ApiBehaviorOptions.ClientErrorMapping

Use the ClientErrorMapping property to configure the contents of the ProblemDetails response. For example, the following code in Program.cs updates the Link property for 404 responses:

builder.Services.AddControllers()
    .ConfigureApiBehaviorOptions(options =>
    {
        options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
            "https://httpstatuses.com/404";
    });

Additional resources

• How to Use ModelState Validation in ASP.NET Core Web API
• View or download sample code
• Hellang.Middleware.ProblemDetails