Does a standard for errors / error codes exist?

Question

I am currently writing an API / some clients for chess games.

The developers should access the API via one script (xhrframework.php) and submit the actions via GET. It is possible that they make some errors when they submit the actions (No PHPSESSID sent, no valid PHPSESSID, move was not valid, it's not their turn, ...).

So I thought about the posibilities how to display errors. I came up with some ideas how to inform the programmer, that he made an error:

1. via an error message in clear english
   • +: It is clear what the error should mean
   • +: Information how to fix this error can be added
   • -: The message might change as my english isn't very good
   • -: The length of the message differs quite a lot - this might be important for C programmers
2. via ab error message constant in english - something like WRONG_PHPSESSID, MISSING_PHPSESSID, INVALID_MOVE, NOT_YOUR_TURN, ...
   • +: It's understandable for a human
   • 0: It's almost sure that the message doesn't change
   • -: The length of the message might differ a bit
3. via an error code with one table in the documentation where the programmer can find the meaning of the error code
   • +: The error code would be constant
   • +: The lenght of every error code could be the same
   • -: It's cryptic

I thoguht the third solution might be a good idea as the xhrframework.php should only be accessed by a programmer who quite possible took already a look at the API documentation.

Now I would like to know if a standard for Web-API-Error messages does exist. How did others (e.g. Google Maps API) solve this? Should I simply output a blank page with the content "ERROR: 004" or without padding "ERROR: 4"?

Which errors should get which numbers? Does ist make sense to group errors by their numbers, e.g. all errors beginning with 1 were authentification errors, all errors with two game logic errors? Would it be better to begin with error 1 and use each number?

Google Maps API

If I make a wrong call to the Google Maps JS-API, it returns Java-Script with a message in clear German (as I live in Germany, I guess).

The Google Static Maps API returns a message as text in clear English if I make a wrong call.

Answer 1

Most API services follow the HTTP error code system RFC2817 with ranges of error codes for different types of error:

1xx: Informational - Request received, continuing process 
2xx: Success - The action was successfully received, understood, and accepted 
3xx: Redirection - Further action must be taken in order to complete the request 
4xx: Client Error - The request contains bad syntax or cannot be fulfilled 
5xx: Server Error - The server failed to fulfil an apparently valid request

In an API context you would mostly use the 4xx values to denote error conditions to do with the validation of requests. 49x are generally used for security error conditions.

Answer 2

There's no standard, and why should there be? Programmers using your interface already have to learn that, which is presumably something custom, so needing to write custom error handling code is just part of the package.

I would suggest you make up a sensible format you will stick with. You could go with the best of each world and include several pieces of information in what you return, perhaps along these lines:

[one of "ERROR" or "WARNING" or "MESSAGE"]
[error code with no spaces, eg "BAD_MOVE"]
[optional human readable string]

That way, if a new error type is invented that old clients don't understand, they can still recognise that the return begins with "ERROR" and know that something went wrong; by parsing for the error code (don't use integers, it's a waste of everyone's time), they can take appropriate action if it's error the programmer has taken into account. Finally, if you put in a friendly string for selected errors, it makes it easy to present something nice to the user or be helpful for debugging.