Rest error message in HTTP Header or Response Body?
HttpRestHttp ErrorHttp Problem Overview
I have a REST service that is exposed to iPhone and Android clients. Currently I follow the HTTP codes 200, 400, 401, 403, 404, 409, 500 etc.
My question is where is the recommended place to put the reason/description/cause of the error? Does it make more sense for the REST API to always have custom Reason in the header like so?
< HTTP/1.1 400 Bad Request - Missing Required Parameters.
< Date: Thu, 20 Dec 2012 01:09:06 GMT
< Server: Apache/2.2.22 (Ubuntu)
< Connection: close
< Transfer-Encoding: chunked
Or is it better to have it in the Response Body via JSON?
< HTTP/1.1 400 Bad Request
< Date: Thu, 20 Dec 2012 01:09:06 GMT
< Server: Apache/2.2.22 (Ubuntu)
< Connection: close
< Transfer-Encoding: chunked
< Content-Type: application/json
{ "error" : "Missing Required Parameters" }
Http Solutions
Solution 1 - Http
Quoting from the HTTP specification for 400.x error codes:
> The 4xx class of status code is intended for cases in which the client > seems to have erred. Except when responding to a HEAD request, the > server SHOULD include an entity containing an explanation of the error > situation, and whether it is a temporary or permanent condition. These > status codes are applicable to any request method. User agents SHOULD > display any included entity to the user.
It is best practice to include the error message as an entity in the body of the HTTP response - be it JSON, plain text, formatted HTML, or whatever other format you may want to utilize.
Solution 2 - Http
It is better to have error details in the body. Furthermore, many (most / almost all, eg. WSGI) servers and clients do not support changing the name of the error code - treat them as fixed pairs (so eg. 400 is always "Bad Request" and not "Bad Request - You Forgot To Specify The User ID"). Even if they won't break, they won't care about your special name for specific error code.
Solution 3 - Http
The error does not belong in the body. It belongs in the Warning header.
> The Warning general HTTP header contains information about possible > problems with the status of the message.