| uid | title | author | description | ms.author | ms.date | ms.assetid | msc.legacyurl | msc.type |
|---|---|---|---|---|---|---|---|---|
web-api/overview/error-handling/exception-handling |
Exception Handling in ASP.NET Web API - ASP.NET 4.x |
Rick-Anderson |
Describes ASP.NET Web API executes error and exception handling and provides examples for errors and exceptions. |
riande |
03/12/2012 |
cbebeb37-2594-41f2-b71a-f4f26520d512 |
/web-api/overview/error-handling/exception-handling |
authoredcontent |
This article describes error and exception handling in ASP.NET Web API.
What happens if a Web API controller throws an uncaught exception? By default, most exceptions are translated into an HTTP response with status code 500, Internal Server Error.
The HttpResponseException type is a special case. This exception returns any HTTP status code that you specify in the exception constructor. For example, the following method returns 404, Not Found, if the id parameter is not valid.
[!code-csharpMain]
For more control over the response, you can also construct the entire response message and include it with the HttpResponseException:
[!code-csharpMain]
You can customize how Web API handles exceptions by writing an exception filter. An exception filter is executed when a controller method throws any unhandled exception that is not an HttpResponseException exception. The HttpResponseException type is a special case, because it is designed specifically for returning an HTTP response.
Exception filters implement the System.Web.Http.Filters.IExceptionFilter interface. The simplest way to write an exception filter is to derive from the System.Web.Http.Filters.ExceptionFilterAttribute class and override the OnException method.
Note
Exception filters in ASP.NET Web API are similar to those in ASP.NET MVC. However, they are declared in a separate namespace and function separately. In particular, the HandleErrorAttribute class used in MVC does not handle exceptions thrown by Web API controllers.
Here is a filter that converts NotImplementedException exceptions into HTTP status code 501, Not Implemented:
[!code-csharpMain]
The Response property of the HttpActionExecutedContext object contains the HTTP response message that will be sent to the client.
There are several ways to register a Web API exception filter:
- By action
- By controller
- Globally
To apply the filter to a specific action, add the filter as an attribute to the action:
[!code-csharpMain]
To apply the filter to all of the actions on a controller, add the filter as an attribute to the controller class:
[!code-csharpMain]
To apply the filter globally to all Web API controllers, add an instance of the filter to the GlobalConfiguration.Configuration.Filters collection. Exception filters in this collection apply to any Web API controller action.
[!code-csharpMain]
If you use the "ASP.NET MVC 4 Web Application" project template to create your project, put your Web API configuration code inside the WebApiConfig class, which is located in the App_Start folder:
[!code-csharpMain]
The HttpError object provides a consistent way to return error information in the response body. The following example shows how to return HTTP status code 404 (Not Found) with an HttpError in the response body.
[!code-csharpMain]
CreateErrorResponse is an extension method defined in the System.Net.Http.HttpRequestMessageExtensions class. Internally, CreateErrorResponse creates an HttpError instance and then creates an HttpResponseMessage that contains the HttpError.
In this example, if the method is successful, it returns the product in the HTTP response. But if the requested product is not found, the HTTP response contains an HttpError in the request body. The response might look like the following:
[!code-consoleMain]
Notice that the HttpError was serialized to JSON in this example. One advantage of using HttpError is that it goes through the same content-negotiation and serialization process as any other strongly-typed model.
For model validation, you can pass the model state to CreateErrorResponse, to include the validation errors in the response:
[!code-csharpMain]
This example might return the following response:
[!code-consoleMain]
For more information about model validation, see Model Validation in ASP.NET Web API.
The previous examples return an HttpResponseMessage message from the controller action, but you can also use HttpResponseException to return an HttpError. This lets you return a strongly-typed model in the normal success case, while still returning HttpError if there is an error:
[!code-csharpMain]