Should the status field in the output of a REST-style API call be a numeric code or a string?

Question

I have a REST-ish API that returns JSON. One of the output fields is status, which indicates if the call succeeded. I gather that it's somewhat standard to use numeric status codes such as

200 success
400 syntax error
401 authentication error
402 general error
404 user not found
408 timed out
500 fatal error
501 not yet implemented

Are there any reasons (other than to transmit slightly fewer bytes) to use numeric codes rather than more descriptive symbols as the status, like

success
syntax_error
auth_error
general_error
user_not_found_error
time_out_error
fatal_error
not_yet_implemented_error

Pointing to modern precedents in well-respected APIs would be helpful.

Answer 1

You can make them what you want, as long as they are standard (across your app) and documented for the benefit of those using the webservice.

The fondness of using HTTP status codes such as 404 is that a true REST webservice is based on HTTP transport, so it makes sense to use recognised standards.

That said, you may find that the HTTP/1.1 status codes are not an exact fit - such as your '404 user not found' equivalent to '404 not found' - I think as long as the meaning is there then fine.

If you have to create completely new codes, it's worth sticking to the HTTP groups - 2xx for acceptable results, 3xx for required changes, 4xx for client-side errors and 5xx for server-side errors.