I'm wondering how to manage empty results returned by search queries in a REST web-service :

I there was a query like my_ressource_collection/{id} and the resource didn't exists i would return 404 - Not Found

But, if my URI is more like a search query like : my_ressource_collection/?fromDate={fromDate}&toDate={toDate}&filter1={filter1}&page={page} : Does the same logic applies ? If no results matchs to the perametters, do I have to return a 404 status ?


4 Answers 4


I think in the most cases the most useful reaction would be to return a regular answer (HTTP 200) and send empty data. For example if you are returning JSON you could send


Another good option may be the HTTP Code '204 - No Content'.

The 4xx codes describe a client failure, so the 404 code wouldn't be a good idea, because it's a valid request, even if there are no matching data.


HTTP status codes are specific to the HTTP protocol. So, if the request is successful, meaning, nothing went wrong with the HTTP negotiation, then you should return HTTP status 200 OK.

The fact that the number of result rows in a successfully completed query happens to be zero is completely irrelevant to the protocol that you use for communication.

So, do not mix the two: return a perfectly valid successful response, carrying an empty result set.

As a matter of fact, in my opinion, even if the execution of your query resulted in an error like "unknown table or view", you should still not mix error codes which are specific to your application with HTTP error codes. As far as HTTP is concerned, there was a perfectly valid HTTP request, which is now receiving a perfectly valid HTTP response, and any information about what your application did while servicing the request, like what the results are, or why the results could not be obtained, should be included within the application-specific payload of the response, and is none of HTTP's business.

  • I agree, but would love for someone to provide a w3c or similarly credible link that supports this statement. Jan 9, 2019 at 0:52
  • 1
    @TroyFolger there is no such link, because what I am describing flies in the face of the w3c and of all established practice in the field of so-called "full stack web development". It is just the realization that smart people arrive to, contrary to what established practices dictate. Other smart people have arrived to the same conclusion, for example, Facebook's graph API will only return HTTP 200 OK and will return application-specific error codes within the application-specific response. The documentation is here: developers.facebook.com/docs/graph-api/using-graph-api/…
    – Mike Nakis
    Jan 9, 2019 at 7:52

No, the same logic does not apply.
204 is the most result for this scenario.
See, the 4xx implicit means that the someone "messed-up" somehow. Either the user entered some invalid info or the interface implementer did not used the Rest API properly, anyhow, the request need some "touch-up"... In the first example, the user entered a invalid info (the id), but in the second, as long as he entered a valid date and etc, no mistakes were made, hence the request was understood and completed with no errors.
200 with a empty JSON is not the best approach because it might lead API users to believe that an error occurred or something.


Either a 204 NoContent or a 200 OK would be fine as long as that is communicated to the consumer in some way.

A query returning an empty result set is not uncommon in programming and therefor shouldn't be strange at an API layer either.

Personally It would depend on the type of query being performed in my API. A standard query that normally returns several rows of data if the parameters match would make me lean towards a 200 OK with an empty result matching the normal behavior of the query.

Ex in JSON:

    'results' : [

However if the query itself was meant to be a location component, think a complicated routing issue, then I would return a 204 NoContent or even a 404 Not Found depending on the severity, so that the consumer could recognize the issue and take additional actions.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.