What HTTP status codes to return on wrong API versions?

Question

I'm designing a simple versioned RESTful API. The version will be specified as part of the media type in the Accept header. I wonder what are the proper HTTP status codes for these cases:

version not yet supported, e.g.

Accept: application/json; version=999.0

version no longer supported
```
Accept: application/json; version=0.1
```

here's a [guide](http://racksburg.com/choosing-an-http-status-code/) for choosing the appropriate HTTP Status Code — Alexandru Marculescu, Oct 12 '16 at 06:24
You can't attach a parameter to media type (content-type) where you don't control the definition. — Julian Reschke, Oct 12 '16 at 06:32

score 1 · Answer 1 · answered Oct 11 '16 at 20:20

Seems you should use 406 Not Acceptable for both cases.

406 Not Acceptable The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

score 0 · Answer 2 · answered Dec 15 '22 at 13:42

According to ASP.NET repo, that would either be 400 or 405, depending on the situation:

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

For more info see: https://github.com/dotnet/aspnet-api-versioning/wiki/Error-Responses

What HTTP status codes to return on wrong API versions?

2 Answers2