Error Responses

The following table outlines a summary of the possible error response codes returned when an API version is unmatched. All of these error codes are always returned in the standard error response format with the HTTP status code 400 (Bad Request).

Error Code	Summary
ApiVersionUnspecified	An API version is required, but was not specified
UnsupportedApiVersion	The specified API version is not supported
InvalidApiVersion	An API version was specified, but it is invalid
AmbiguousApiVersion	An API version was specified multiple times with different values

API Version Unspecified

By default, 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 standard error response where the error code is ApiVersionUnspecified. This behavior is typically not exhibited when the AssumeDefaultVersionWhenUnspecified option is configured to true.

Unsupported API Version

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

Invalid API Version

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 standard error response where the error code is InvalidApiVersion. This typically occurs where the value contains incomplete version components or the date-only form is invalid (ex: 2016-02-30).

Ambiguous API Version

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 standard error response where the error code is AmbiguousApiVersion.

Example of Valid Request with Multiple API Versions

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

Examples of Invalid Requests with Multiple API Versions

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

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

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