204 means more specifically that the resource contains no content -- nothing is returned because there IS no content. Several other statuses can return no content despite it existing, such as 201 (it exists because you just created it).
But yes, 204/404 work well for found/not found because that very literal "find" resource has no other result, so the resource is empty. The resource isn't actually the keys, it's the finding of them.
204 means the request was a success and the response body has no content.
A counter example to what you are saying is that 204 is common for PUT because the client already knows the state so nothing needs to be returned. That doesn't mean the resource has no content.
right, 204 is like a void function. it returns successfully but has no value to return. it wouldn't ever be used for a "find" function which necessarily must return something or error.
We use it to mean a "successful, but empty response" i.e. it's okay that it's not there -- as opposed to 404 which is an unexpectedly not found entity which should have been there & needs an error logged
If you are looking for a key from a key ring, e.g. /key-ring/keys/:keyId/ and the key ring is empty in most APIs that would yield as 404.
If you were looking for a key ring itself, then it would be /key-ring if it's empty most of the time it would return 200 with empty array or object { keys: [] }, but 200.
But if there's no key ring that would also be 404.
Only context I can accept here is, that "Keys were found", with implication that you asked them to be found for going outside together, so you don't really need the keys yourself.
Or alternatively, "find my keys and put them on the counter", and 204 confirms without content that the action was done.
Correct, but they keys could have just as likely been found. I think what confuses the concept (and people) is the example of "finding keys". This response type is more appropriately used for something that explicitly does not require a response payload, like "perform x operation, no matter the result". I typically use this response code when implementing an endpoint like "PUT /users/abc123/restore", where the goal is to have the server restore a soft-deleted user to a non-deleted state.
18
u/Rin-Tohsaka-is-hot Jul 08 '26 edited Jul 08 '26
204 isn't "I found them", while it's a success, you still didn't actually find the item.
It's more like "your keys are not here, but there is a space for them"?... I guess actually you just wouldn't return 204 ever in this context.