API: what HTTP status code to use for multiple items found error?

Question

Suppose there is a lookup API endpoint. A response can be successful (200), not found (404), ... and in my case more than one item found is an error. Which HTTP status code can describe more than one item found error the best?

Answer 1

Suppose there is a lookup API endpoint. A response can be successful (200), not found (404), ... and in my case more than one item found is an error. Which HTTP status code can describe more than one item found error the best?

The server fully understands the request, but can't deliver a representation that meets its part of the contract.

So the right error code is going to be in the 5xx range.

The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method.

If none of the specialized 5xx error codes fits, you should use 500

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

Michael Kropat did a good job of enumerating the options in Stop Making It Hard. He makes this interesting observation about 502

I can tell you we would have saved hours upon hours of debugging time if only we had distinguished 502 Bad Gateway (an upstream problem) instead of confusing it with 500 Internal Server Error.

The modern definition of "gateway" can be found in RFC 7230 section 2.3 (Intermediaries).

A "gateway" (a.k.a. "reverse proxy") is an intermediary that acts as an origin server for the outbound connection but translates received requests and forwards them inbound to another server or servers. Gateways are often used to encapsulate legacy or untrusted information services, to improve server performance through "accelerator" caching, and to enable partitioning or load balancing of HTTP services across multiple machines.

All HTTP requirements applicable to an origin server also apply to the outbound communication of a gateway. A gateway communicates with inbound servers using any protocol that it desires, including private extensions to HTTP that are outside the scope of this specification.

Very very roughly, 500 is "my bad", where 502/504 points a finger somewhere else.

what error code would you use for my case?

Based on what you have described, 500. That's appropriate for "my representation of this resource is corrupt."

The reasonable alternative is 502, which is appropriate for "the upstream representation of this resource is corrupt".

In either case, the audience for the error is internal (the client can't do anything to correct the problem. Your support team probably can't do anything useful with the distinction between the status codes). You could just as reasonably argue that the fact that the problem is upstream is an implementation detail of no interest to clients (so 500 everything). Alternatively, you could argue that your API is a gateway that translates received requests and forwards them inbound to another server, and therefore the status code should because the problem is in your store, not in your api.

So it comes down to things like "when tracking the number of errors we have in the api, do we want to distinguish this sort of issue from an exception being thrown internally"?

Authoritative guidance seems to be lacking; choose a method, document your justification, and ship.

Answer 2

That's an interesting problem. If it's an API call for a lookup and you get multiple results back, I'm actually expecting a 200 code with an results array.

But if the request itself is wrongfully formatted, so that it's not clear what it is the client is asking for, you could send a 400 bad request http status code.

Also have a look at the 207 multi-status code, as this might actually closer what you're looking for. Could you maybe provide request and response examples?