Error Responses

There are several built-in error responses. The body of each error response complies with [RFC 7807: Problem Details].

Note

In earlier versions, the error responses bodies complied with the [Microsoft REST Guidelines error response format], which is itself the error response format used by the OData protocol (see [OData JSON Format §21.1]). There wasn’t a broad standard at that time, which made any common error response format sensible.

Each problem detail also contains a code extension to retain a level of backward compatibility for clients that may have relied on that value. If you need to retain the old functionality, refer to backward compatibility below.

Unspecified

All versioned services require that an API version be specified. When a client makes a request without providing an API version, then the server will respond with a bad request. This behavior is typically not exhibited when the API is version-neutral or the AssumeDefaultVersionWhenUnspecified option is configured to true.

Unsupported

When a client requested API version does not match any of the available controllers or their actions, then the server will respond with a problem. If the ReportApiVersions option is true, then the supported versions will be returned to the client in the api-supported-versions HTTP header.

_{1: Defined by ApiVersioningOptions.UnsupportedApiVersionStatusCode
2: The value is always 404 when versioning by URL segment}

Invalid

When a client makes a request with an API version, but the value is malformed or cannot be parsed, then the server will respond with a bad request. This typically occurs where the value contains incomplete version components or the date-only form is invalid (ex: 2016-02-30).

Ambiguous

When a client requests a specific API version, the specified API version must be unambiguous to the server. A client is allowed to specify an API version more than once, but if the values are not identical, then the server will respond with a bad request.

Examples

GET /resource?api-version=1.0 HTTP/1.1
host: localhost
api-version: 1.0

Figure 1: Multiple, unambiguous API versions requested

GET /resource?api-version=1.0 HTTP/1.1
host: localhost
api-version: 2.0

Figure 2: Ambiguous API versions requested between in query string and headers

GET /resource?api-version=1.0&api-version=2.0 HTTP/1.1
host: localhost

Figure 3: Ambiguous API versions requested in the query string

GET /resource HTTP/1.1
host: localhost
api-version: 1.0
api-version: 2.0

Figure 4: Ambiguous API versions requested in the headers

Customization

Error responses can be customized or extended in a variety of ways. RFC 7807 was ratified after active development on ASP.NET Web API ceased. There are no out-of-the-box services provided. API Versioning provides a backport of the ProblemDetails type as well as the IProblemDetailsFactory. The default implementation can be replaced by implementing IProblemDetailsFactory and exposing it as a resolvable service via HttpConfiguration.DependencyResolver.

Backward Compatibility

While it is possible to customize error responses and retain the previous Error Object format, there is considerable work required to enable this behavior and may block adoption of new library versions. Additional extensions have been added to retain backward compatibility or continue to use Error Objects if you so desire.

ASP.NET Web API does not provide an out-of-the-box dependency injection container; however, the following extension method will wire up the necessary changes without having to add one of your own.

configuration.ConvertProblemDetailsToErrorObject();

Note

Applies to 7.1.0+