HTTP status code for "no data available" from an external datasource

Question

Scenario:

A POST request is sent to process an order that will result in data retrieval from an external datasource.

There are three possible results:

1. The datasource returned data for the request
2. No data was available for the request (this is viewed as an error)
3. The datasource couldn't be accessed (may be down for maintenance)

An obvious response for 1 is 200: OK or 201: Created (an entity is created from this request).

What status codes would be appropriate for 2 and 3?

Status codes I have considered:

• 503: Service Unavailable when datasource is down
• 500: Internal Server Error when datasource is down
• 502: Bad Gateway when "no data available"
• 404: Not Found when "no data available"
• 403: Forbidden when "no data available"
• 412: Precondition Failed when "no data available"

Ectomy

Are you trying to query data using a POST request? Shouldn't you be the using GET method? – Valance

GET isn't appropriate because these data queries are neither safe nor idempotent (they may result in the exchange of money among other things). – Ectomy

For 2. I would split into multiple cases. If no post data is given we should throw an 400 Bad Request. If a mandatory field is not set but other data is correct raise an 412 Precondition Failed. – Effectuate

Answer 1

2) Looking back at this, I agree it should probably be either a 204 No Content or maybe a 200 with a body indicating no records or resources could be found depending on the structure returned. 404's are generally used when the resource URI doesn't exist or a resource in the URI is not found in the case of a restful service.

3) 503 Service Unavailable

The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.

  Note: The existence of the 503 status code does not imply that a
  server must use it when becoming overloaded. Some servers may wish
  to simply refuse the connection.

Organicism

If a request is accepted by the server at this resource, but no data was available to return - then 404 makes little sense. Unfortunately, I don't think there is a clear status code that makes sense here, but I'd tend to lean more towards the answer of 204 (or potentially even a 200 with a body that indicates "Data Unavailable"). – Senegambia

204 is definitely wrong if the http request is considered a failure. – Dedifferentiation

Depends on what 'considered a failure' means if you are searching for something and no results are returned a 204 may be acceptable. The OP really didn't provide enough detail for a definitive answer. All we really have to go off is 'No data was available for the request' the case of an issue contacting the data source is handled separately so all that really leaves is that someone is making a request for data that doesn't exist, that doesn't really seem like an error condition so 2xx range does seem reasonable. – Organicism

200 with return message also make sense otherwise 400 also applicable considering it as a bad request – Cryptomeria

Answer 2

3) I agree with 503 for this

2) Frankly I think a good argument could be made for using 204 in case 2 You can include metainfo in the header to indicate specifically what 'went wrong'. It really depends on how much you consider this case to be 'an error' at the API level.

If the API itself is functioning as intended, and the request was to a valid endpoint, by an authenticated and authorized user and did not cause the server to malfunction, then very few of the 400 or 500 series errors would really seem to apply.

for example, 404 usually means the URI you called does not exist, if it does exist, then using that code is misleading at least IMHO

**10.2.5 204 No Content**

The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.

If the client is a user agent, it SHOULD NOT change its document view from that which caused the request to be sent. This response is primarily intended to allow input for actions to take place without causing a change to the user agent's active document view, although any new or updated metainformation SHOULD be applied to the document currently in the user agent's active view.

The 204 response MUST NOT include a message-body, and thus is always terminated by the first empty line after the header fields.

Breastsummer

Another "popular" way this seems to be handled, is by returning an error message or empty response with a 200 HTTP status code. This has also been touched on at #11402656 – Equivocation

I would avoid returning a 5xx status code if no error occured in the processing of the request by the server (i.e. everything goes fine, except that there is no data available). In the described scenario, nothing is wrong with the server but rather with the client, that requested something it shouldn't had. So I would advise using a 4xx status code such as 400, 404 or 406. – Cloudy

Scenario 3 'datasource unavailable' as described in the question would seem to be an actual situation where something is 'wrong' 503 would be appropriate there, but as I said not for scenario 2 where systems are working but data just doesn't exist in the system – Breastsummer

Answer 3

HTTP 404 - With your own error message like "No data found".

Twitter uses 404. Reference: https://developer.twitter.com/en/docs/basics/response-codes.html

Xi

The link is broken – Monaxial

Twitter uses 404. Reference: developer.twitter.com/en/support/twitter-api/… – Acrodont

Answer 4

1. The datasource returned data for the request

200: OK/201: CREATED
Because everything is working as expected

2. No data was available for the request (this is viewed as an error)

400: BAD REQUEST
The request was invalid or cannot be otherwise served. An accompanying error message will explain further inside the body.like:
HTTP 400
{
response: null,
code: "USER_101", //should be used customized error codes here
error: "User details not found"
}

3. The datasource couldn't be accessed (may be down for maintenance)

404: Resource/URI NOT FOUND
The URI requested or resource is invalid
Like: https://www.lipsum.com/list-page
**/list-page** is not defined/found

Find here most frequently used status codes:

200 – OK
Everything is working, The resource has been fetched and is transmitted in the message body.

201 – CREATED
A new resource has been created

204 – NO CONTENT
The resource was successfully deleted, no response body

304 – NOT MODIFIED
This is used for caching purposes. It tells the client that the response has not been modified, so the client can continue to use the same cached version of the response.

400 – BAD REQUEST
The request was invalid or cannot be served. The exact error should be explained in the error payload.

401 – UNAUTHORIZED
The request requires user authentication.

403 – FORBIDDEN
The server understood the request but is refusing it or the access is not allowed.

404 – NOT FOUND
There is no resource behind the URI.

500 – INTERNAL SERVER ERROR API
If an error occurs in the global catch blog, the stack trace should be logged and not returned as a response.

Gallnut

Answer 5

In my opinion the best way to handle this is with a 200 no result object.

Why?

You have a response that you can do something with without a lot of trouble. I searched, everything worked correctly but there wasn't anything in the database to give a result. Therefore, result = null and a message explaining as much. If something found this in the network calls it is not a security risk.

If you are concerned with a security risk then a 204 is probably the best approach.

res.status(200).send({
   result: null,
   message: 'No result'
});

Dacha