Which http status code to use for no search results found?

Published on July 04, 2020

I was implementing a search REST API and was thinking about the no results status. There are a couple of options that are somewhat valid. There is no perfectly “right” answer and the discussion exposes care for API design, knowledge of http and care for developers who will be consuming the api.

The scenario

Say we are searching some rest api for results GET /api/collection?filter=value&filter=value. What should the API return if there are no results?

The go-to response for a non-error is of course 200 OK but I wanted to think it through instead of defaulting to OK. The analysis depends on HTTP code RFC interpretation and conventions around what is a REST response. It’s subjective.

I still ended up preferring 200.

404 Not Found

Not Found sounds like an option that could work well but the 400 series of response codes are used to indicate that the user request was in error.

This is valid in the case where a single entity requested by the user doesn’t exist. The user asked for a resource that doesn’t exist. They should change their request.

But no search results is not a user error (depending on your api of course). No results is an expected response from a collection api like a search filter.

In this endpoint the resource is the collection itself. The collection should exist. Using a 404 could also lead a developer to think that your endpoint/collection doesn’t actually exist when in fact it’s just that there is no data. This could waste a lot of time.

For an issue where the developer tries to search a collection that doesn’t exist. I would return a 404.

204 No Content

No content also sounds like something that might be appropriate. The search was successful but there are no results. This is semantically correct. However the RFC states that

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

So I don’t like this for the fact that a client has to handle no response body. It’s not the worst choice but it feels wrong.

200 OK

This is a great option. It’s straightforward. The request itself was successful.

I feel that having a consistent array in the body is easier to work with and since we design APIs to be consumed as easily as possible.

A 200 OK is the way to go and I was just over thinking this!

Darragh ORiordan

Hi! I'm Darragh ORiordan.

I live and work in Sydney, Australia building and supporting happy teams that create high quality software for the web.

I also make tools for busy developers! Do you have a new M1 Mac to setup? Have you ever spent a week getting your dev environment just right?

My Universal DevShell tooling will save you 30+ hours of configuring your Windows or Mac dev environment with all the best, modern shell and dev tools.

Get DevShell here: ✨ https://devshell.darraghoriordan.com

Read more articles like this one...

List of article summaries


Building an AI generated game with Stable Diffusion and data from Wikipedia

Last week I released a game called Doodle:ai.

In the game you’re shown AI generated images and you have to guess the Wikipedia topic it used to create the game.


Easiest way to optimise images for web

Here is how I optimise all pngs and jpgs in a folder for publishing to the web.


Start tracking DORA metrics for your team in just 15 minutes with Apache Dev Lake

DORA (DevOps Research and Assessment) metrics are an excellent way for engineering organisations to measure and improve their performance.

Up until now, monitoring the DORA metrics across Github, Jira, Azure Devops etc required custom tooling or a tedious manual process.

With Apache Dev Lake you can get beautiful reporting for DORA metrics on your local machine in as little as 15 minutes (honestly!).

From Google Sheets to Grafana
From Google Sheets to Grafana


A summary of NDC Sydney 2022 Developer Conference

I attended my first in-person conference for more than 3 years last week! NDC is one of the more well-known developer conferences in Australia and New Zealand. It’s a 5 day conference with 3 days of talks and 2 days of workshops.

There’s so much to learn across all the streams so I try to take notes for each of the talks to quickly reference them later. This post contains all my notes. I’ll add the relevant videos to talks later if they’re released.

A reminder that these notes are just my notes. They’re paraphrased and summarised from what the speaker actually said. Each speakers would have provided must more clarity and went into more detail during their pressos!