HTTP Status Code for Client being out of date

Question

I'm working on moving my REST API away from always responding with a STATUS: 200 OK containing an error key in the JSON returned if there was a problem, and trying to use the correct status codes in the event of problems.

So far I've moved most parts of my server over to the proper status codes 200, 201, 400, 401, 403, 404, 500, 501, and 503

Currently I'm trying to figure out what the best way of rejecting the access to a API call for a client that is out of date. Currently I'm sending the version of the client encoded with the Authorization token.

I'm stuck between using status code 426, and 412. The title of the 426 status code seems like the use case I would want, but the description has me a little concerned. 412 looks like it would be appropriate if i moved my versioning away from the authorization token and put it inside of it's own header.

This is my first REST API, and it works great, I'm just trying to convert it to following best practices. So I'm a little boggled.

TLDR;

• Should I move my versioning into Headers and use Status 412
• Should I use status code 426
• Is there a code I'm missing here I should be using to request the client to update.

NOTE: My client is not a web browser. It is a mobile device.

Answer 1

Let us walk through your proposed solutions real quick: Status code 412 is now under authority of RFC 7232, section 4.2. It is to be used in the context of conditional requests if one or more preconditions described in section 3 of said RFC prevent the given request from being completed.

Code 426 is subject to RFC 7231, section 6.5.15. This code lets the client know that the [http] protocol version used to access a resource is too old to complete the request. Both of these codes do not apply here.

With a bit of help from this chart, I think two codes were adequate here:

• Code 400 / Bad Request

400 is a bit vague (and delibertaly so), indicating a general issue with the request.

• Code 403 / Forbidden

This is a bit of a stretch as this code is indicating an authorization issue. However, it is not inherently linked to authentication, so you should be fine here.

Personally, I would go with 400. You may also want to take a look at RFC 7807 for a standardized way of transmitting API errors.