Error 426 upgrade required

I have a mobile device communicating via HTTPS to a RESTful API on my servers. One of the operations is a data sync to push modifications made while offline to the server and pull down updates made in parallel on the server.

I’ve encountered an edge case where that sync operation can fail silently in the existing client. I’ve upgraded the «sync protocol» on the client to handle the condition properly. Ideally I’d like to have all older clients receive a message when they try to sync telling them to upgrade.

The communication is just between my server and my mobile client so I realize I can return any number of HTTP codes and signal the client to display a message in the future advising the user to upgrade and to immediately stop the sync process.

Would it be seen as a bastardization of the intent of the HTTP 426 Upgrade Required return code to use it to signal this. Every reference (IETF RFC 2817, Wikipedia) I can find speaks to using it to signal a client to upgrade to TLS. Is it meant to be limited to well defined/security protocols like SSL and TLS or is it a generic upgrade flag at the HTTP layer which has only been used for SSL and TLS traditionally?

If it isn’t intended for this use case would a HTTP 303 See Other be considered more appropriate or is there another code I’m missing?

Quoting one of my previous answers:

HTTP Upgrade is used to indicate a preference or requirement to
switch to a different version of HTTP or to another protocol, if
possible:

The Upgrade general-header allows the client to specify what 
additional communication protocols it supports and would like to use 
if the server finds it appropriate to switch protocols. The server 
MUST use the Upgrade header field within a 101 (Switching Protocols) 
response to indicate which protocol(s) are being switched.

      Upgrade        = "Upgrade" ":" 1#product

  For example,

     Upgrade: HTTP/2.0, SHTTP/1.3, IRC/6.9, RTA/x11

The Upgrade header field is intended to provide a simple mechanism 
for transition from HTTP/1.1 to some other, incompatible protocol.

According to the IANA register, there are only 3 registered
mentions of it (including one in the HTTP specification itself).

The other two are for:

• Upgrading to TLS Within HTTP/1.1 (almost never used, not to
  be confused with HTTP over TLS, which defines HTTPS as widely
  used). This upgrade allows for a similar mechanism to STARTTLS in
  other protocols (e.g. LDAP, SMTP, …) so as to be able to switch
  to TLS on the same port as the plain connection, after exchanging some
  of the application protocol messages, as opposed to having the entire
  HTTP exchange on top of SSL/TLS without it needing to know it’s on top
  of TLS (the way HTTPS works).

• Upgrading to WebSockets (still a draft).

(The IANA register hasn’t changed since then.)

The 426 response code as defined in RFC 2817 clearly has to do with an upgrade in the «HTTP Upgrade» sense defined in RFC 2816. This is a change of the current protocol at the layer currently used (i.e. HTTP itself). (It’s not even about upgrading from http:// to https:// at all.)

The messages exchanged on top of HTTP (if part of a protocol at all) are not part of this. They’re just hypermedia entities as far as HTTP is concerned.

I don’t think 426 would be suitable if you change the meaning of your hypermedia. A plain 400 would probably be a better choice. Note that responses with error status codes (4xx, 5xx) do not prevent you from associating an entity in the response: this is where a message telling the client to upgrade your protocol (at that level) should be.

I agree with Bruno that 426 is not the best choice. 400 is better, but I think 403 is better still.

10.4.4 403 Forbidden

The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. If the request method was not HEAD and the server wishes to make public why the request has not been fulfilled, it SHOULD describe the reason for the refusal in the entity. If the server does not wish to make this information available to the client, the status code 404 (Not Found) can be used instead.

There is precedent for this on the Twitter API.

Since Feb 26, 2014, api.twitter.com is returning 403 status code for all non-SSL incoming traffic. Your client code should be able to handle this error.

answered Apr 17, 2014 at 1:05