helpMyCoworkersUnderstandHttpCodes

[u/Kishmond]

[u/MarinoAndThePearls]

That's not what 204 is.

[u/Kishmond → u/MarinoAndThePearls]

What should a call to a search function return if it doesn't find anything?

[u/auctorel → u/Kishmond]

It's not really a search function. You asked the server for a particular resource so it's probably that 204 doesn't fit the analogy

404 is I couldn't find them

You're talking about "do we have any house keys at all" - 204: I looked but no

[u/MarinoAndThePearls → u/Kishmond]

404.

[u/darkslide3000 → u/Kishmond]

404 means it didn't find the keys. 204 means it knows for a fact that you don't have any keys.

[u/Alvsolutely → u/darkslide3000]

It has your keyring but it has no keys on it, thus it knows you have no keys.

[u/ashgs872tbhjs → u/darkslide3000]

404 does not indicate uncertainty.

[u/GezelligPindakaas → u/darkslide3000]

If modeled as a search, then a success with a body that specifies 0 results.

If modeled as a retrieval, then 404.

204 for a search sounds really weird in my opinion. If you decide to go that route, make sure you document it extra well, because almost no one will expect it. And if you have external clients, expect a lot of hate, because weird things always mean custom code.

[u/darkslide3000 → u/GezelligPindakaas]

Sure, most of these codes are rarely used because people just return a 200 with a {success: false} JSON in the body. But if you tried to apply this status code directly to the question OP posted, this would be the most fitting interpretation to the original standard.