httpresthttp-status-codesrestful-architecture

HTTP status code when single request asks for too large resource or too many of them


Does somebody know which HTTP status code is the right one for the following situation?

An anonymous client can request a range of items from a collection from RESTful API with GET /collection/?range_start=100&range_end=200. The example query returns a list with 100 items (in JSON). There is also a limit, lets say 300, for how many items the client can request. What should the response status code be if the client asks for example 1000 items in the range [100, 1100] what means 700 items over the limit?

Should it be 400 Bad Request, 403 Forbidden, 409 Conflict, 416 Requested Range Not Satisfiable(?) or 422 Unprocessable Entity? What would you recommend?

A related question and answer propose 409 but the situation is slightly different: https://stackoverflow.com/a/13463815/638546


Solution

  • 403 sounds like the most appropriate choice. It basically says "nu-uh. You don't get to see that.", which is pretty much the case here.

    10.4.4 403 Forbidden

    The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated. [...]

    Of course, it'd be a good idea for the response body to include the reason you're refusing the request.

    All the other codes seem to me to have specific meanings that disqualify their use here.

    400 is not quite appropriate because the request is valid, and you understand it just fine; it's just asking for more than you're willing to send at once.

    409 is not appropriate because it's specifically related to the "state" of the resource. (It is appropriate for the question you linked, because in that case the error was adding to a collection that was already "full". In your case, though, it's not the resource that has a problem; it's the request.) Also,

    This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.

    where by "resubmit" the standard means "repeat". In this case, no matter what the client does, that request will be invalid.

    416 specifically refers to the "Range" header, so it's out altogether.

    417 likewise refers to a header field (in this case "Expect"), so it's likewise out.

    422 is not appropriate because it specifically means you sent an entity that is syntactically correct, but is still broken. Since GETs traditionally have no request body (no entity), there's nothing to be unprocessable. If the client were POSTing a request, you might almost have a case...but then, you'd also have to make a good case for why a RESTful API requires a POST that doesn't update anything.

    (I'm about 47% sure that the code also doesn't make much sense outside of WebDAV...but it does seem there are conceivable use cases. Just not this one.)