Responses for RESTful webservices in a case of error

[Ekaterina Galkina]

I'm creating JSON RESTful webservices and can't decide on what to return. For example, the request is to create a user

POST /user

{
   "name": "Jane", 
   "email": "[e-mail]"
}

What to return if there was an error creating user? I can set status code HttpStatus.CONFLICT (409) or return 200 but design a special field in JSON for status:

{
   "status": "error"
}

.
What's the common practice: status code or include status into the body response? I've seen the first variant in internet, is that correct (Status-Code 409 , no body) ?

[Pete Letkeman]

From what I gather the HTTP status code like 200, 400, 404 etc should be used for the information about the communication stream.
For instance a 200 means that the request for content successfully occurred and a 404 means that content cannot be found.

When doing a REST request if the request succeeds then you should use an status code field like to signal that the data can or cannot be processed:
{   "status": "success" }
or
{   "status": "error" }
This is due to the fact that even though the HTTP request is fine the data returned may not be for whatever reason.

[Pete Letkeman]

According to Wikipedia here are the HTTP status codes and what they mean:
https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
You may have to judge for yourself if a 409 HTTP status code is the code to use.
It could may perfect sense, it may not depending on the use.

[Ekaterina Galkina]

Pete Letkeman wrote:
{   "status": "error" }
This is due to the fact that even though the HTTP request is fine the data returned may not be for whatever reason.

Could you give an example? For example, the user with such email exists, that's why can't be a added to the databse. We set the status code 409 - conflict. Should we also include json error status to the body in such case?

[Pete Letkeman]

Ekaterina Galkina wrote:Could you give an example? For example, the user with such email exists,

I can try, please bear with me for a moment or two.

With a 409 error you are indicating that the communication between the client and the server reported an error. You may not know what that error is, as a 409 error could mean that the user is in the DB and cannot be added.
However with a 409 error you could also indicate that the account was updated incorrectly, but the data is still usable/stable.

A 409 error could be 100% fine, as it does signal and error, however depending on where the error occurred you may want to do different actions.
The many HTTP status codes describe communication between the client and the server.

As to when you may want to use a error field in your content?

Suppose a user wants to change their username (for whatever reason).
Now, you can only change your username when the username that you want to use is not currently is use.
"Simple" right? Maybe not.
Well suppose that you have a user base of a few thousand and anyone at any point in time could try this and in theory you could end up with two people moments apart trying to change to the same username.
The second user would get a 409 response and the status code could be:
{   "status": "error, username taken" }
Here you are using the 409 to signal the error and the status field to give the error context.
You may want to split this up into
{   "status": {"error", "username taken"} }
Yet you may not be too concerned with the reason of the error, only that there is an error. It is up to you what exactly you do.
You could change and not use a 409, but only rely on a status of 200. and the error field. Problem is that not every client is going to be able to understand that, and they may not be able to read the status field.

So in the it looks like you would probably want to use both the HTTP status codes and the JSON status field.
As to which HTTP status code to use? That depends on what you wish to convey.
A 409 could perfectly fine, but then again 400 could be used the same way.
A lot of the time a HTTP status of 4XX or 5XX means a serious error occurred.

Hope this cleans things up a bit, but I admit it may not.

[Ekaterina Galkina]

So is the status field needed just to clarify the reason or the error?

[Pete Letkeman]

Ekaterina Galkina wrote:So is the status field needed just to clarify the reason or the error?

Yes, that is the way that I would do it. That does not mean it is correct.
In theory all of your clients can understand the HTTP status code and they need to check that first.
Not all of your clients may understand the JSON status field.

[Ekaterina Galkina]

May be it's correct to include error status into header, but Google Maps RESTful API returns 200 and includes error into json body.

For example, https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670,151.1957&radius=500&types=food&name=cruise&key=YOUR_API_KEY

HTTP/1.1 200 OK

{
   "error_message" : "The provided API key is invalid.",
   "html_attributions" : [],
   "results" : [],
   "status" : "REQUEST_DENIED"
}

[Pete Letkeman]

Yes, you can include a lot of information in the HTTP header, including custom data and error messages if you choose to.
As you may have guess by now there isn't a 100% standard that everyone follows.

If you are only given a HTTP status code and nothing else then you may not be reasonably able to correct your actions.
Sometimes this is 100% fine. You have most likely had a 404 and there was nothing that you could do to correct this.

For many clients, Windows, Mac/IOS, Android the HTTP status trumps everything.
They first check to see if the HTTP status is within the 2XX range to see if the content can be processed.
If the HTTP status is not 2XX then they know that the content cannot be processed.
However if the HTTP status is in the 2XX range then the client is expected to be able to process the content. This could include looking for a status field to see if the content should be processed.
Anything that is in the 4XX or 5XX range is usually a hard error, with which you cannot do too much about.

In Google's case, as listed in the previous post, Google wants you to be able process the content and show you why you are not getting the results that you may have expected so that you can take corrective actions.
This also helps with self documentation to a degree.

[Ekaterina Galkina]

BTW, is it POSSIBLE to include message body into 4XX response and doesn't it violate any rules? I have this question because I've never seen any content in browsers if a page can't be loaded because of 4XX error.

[Pete Letkeman]

Ekaterina Galkina wrote:BTW, is it POSSIBLE to include message body into 4XX response and doesn't it violate any rules

It may be possible. This depends on how the web server handles these types of messages.
You can defiantly have a custom 4XX page which display static content.
However I think that some servers can have custom 4XX pages with dynamic content.

Ekaterina Galkina wrote:I have this question because I've never seen any content in browsers if a page can't be loaded because of 4XX error.

Most of the time the web browser does not show the HTTP headers, as it's usually concerned with the HTTP body.
Yet you can put a fair bit of content into the HTTP headers. If it's too much then the client will simply ignore the content.

So in theory this is 100% possible, but I'm not too sure about practice. Simply due to the fact that 4XX and 5XX error are usually very serious errors and you can save resources if you don't provide content that nearly no client will use anyway.

[Ron McLeod]

Ekaterina Galkina wrote:... What to return if there was an error creating user? I can set status code HttpStatus.CONFLICT (409) or return 200 but design a special field in JSON for status ...

Only return a 2XX response (typically a 201 Created) if the resource was actually created (along with a HTTP Location header with the URI for the newly created resource).  Messaging processors normally will not look in to the payload provided with your response, so sending a 200 OK response with an error message in the body will be understood as the transaction having completed successfully.

If the resource could not be created, return the appropriate 4XX or 5XX response which best indicates the reason why.  For example:
    400 Bad Request - invalid or missing required parameters
    401 Not Authorized - requestor not authorized (usually triggers client-side to provide credentials or answer to a challenge)
    403 Forbidden - request not permitted to perform operation - don't bother trying again
    406 Not acceptable - resource representation not supported by server (eg - server only supports JSON, requestor provided XML)
    409 Conflict - resource alerady exists
    500 Internal Server Error - unexpected error while processing request
    503 Service Unavailable - dependent system/subsystem not available (eg - cannot connect to data store)

If you can put enough information in the response text, then you don't need to provide a body with the response.  If you do need extra information, return an a payload with the details.

[Ekaterina Galkina]

Thank you

Ron McLeod wrote:
    401 Not Authorized - requestor not authorized (usually triggers client-side to provide credentials or answer to a challenge)

And what's the reason why Google returns 200 if requester not authorized - API key not provided
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670,151.1957&radius=500&types=food&name=cruise&key=YOUR_API_KEY

[Ron McLeod]

Pete Letkeman wrote:From what I gather the HTTP status code like 200, 400, 404 etc should be used for the information about the communication stream.

The response codes do not reflect the success or failure of the data transmission.  In most cases they provide an indication of the result of the actual processing of the request by the server.  Sometimes, the client agent may generate the return code itself base on connectivity issues, but tis is an exception - for example, the client side may generate a 408 Request Timeout towards the application when it cannot establish a connectino to the server.

[Bear Bibeault]

Ekaterina Galkina wrote:Thank you

Ron McLeod wrote:
    401 Not Authorized - requestor not authorized (usually triggers client-side to provide credentials or answer to a challenge)

And what's the reason why Google returns 200 if requester not authorized - API key not provided
https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=-33.8670,151.1957&radius=500&types=food&name=cruise&key=YOUR_API_KEY

Because that has nothing to do with browser authorization. Providing your API key is not authorization. It just gives them something to track bandwidth against. Triggering the browser to ask for a username and password isn't what the API needs.