Standardize API response codes?

[mozumder]

Should we push for a standard set of API response codes for API servers? Similar to what HTTP has in their response codes? (404, 200, etc..)

There could be hundreds of possible response codes:

1. Not Found
2. OK
3. Invalid API Key
4. Service Unavailable
5. Permission denied etc..

[AndySky21]

I advise you not only to suggest a set of API response codes, but also to have them constituting a superset of HTTP response codes. For instance, it would be a good idea to have 2- or 3-digit codes, so that language can evolve (for example, you could have 301 unsupported API key instead of 302 outdated API key - replacement provided, or 501 authentication required rather than 502 client is not allowed to perform this action and so on). Consider having them ordered in a "decreasing success level" list (not increasing - success is a simple achievements, while reasons for failure can increase), so that you can process status code with JS and recognize that, if code is above a threshold, the data call has failed (and if it is above another threshold, it is a server failure rather than a wrong call etc.).

In parallel to this, I guess you should also have a set of client API status codes for loading/updating content, similar to XHR, in order not to rely upon whether content has been sent, but also if they've been properly received and processed. Here you need the opposite logic: increasing success rate. This is because you already know you've met a positive response from the server and action is proceeding. But, if user agent is unable to furtherly process instructions (e.g. connection latency, memory leak), it could be unable to tell you why. For example, if user is operating on a mobile, non-constant connection, s/he could experience a latency due to disconnection/connection failure/temporarily insufficient bandwidth. However:

• the first case is a stable failure which could be easily recognized by the platform
• the second, though recognizable, could be temporary
• the second is both temporary and not recognizable, unless you constantly interrogate the system about bandwidth speed.

So instead of having failure codes, all you need is a sequence of success steps (0 - not sent, 1 - sent, 2 - HTTP header received, 3 - loading data, 4 - done, 5 - target element recognized, 6 - target content refreshing, 7 - content updated successfully) and a fallback function can be implemented if latency between two steps lasts too much (however, latency time cannot be standard but authors must tailor it according to expected content, expected bandwidth speed etc.)