30

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

Community
  • 1
  • 1
Akseli Palén
  • 27,244
  • 10
  • 65
  • 75
  • Since a part of the api contract is the hard limit of 300 items total, since the client violates this, the server should respond with 400. – Pawel Zieminski Feb 17 '22 at 03:00

2 Answers2

27

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.)

Community
  • 1
  • 1
cHao
  • 84,970
  • 20
  • 145
  • 172
  • No, 422 is not specific to WebDAV. But it is indeed not the right status here. – Julian Reschke Mar 04 '13 at 08:33
  • @JulianReschke: Status code 422 is defined in [RFC 4918](http://datatracker.ietf.org/doc/rfc4918/?include_text=1), which describes WebDAV...and nowhere else i can find. If a server sent that back to me while i was doing non-WebDAV-related stuff, i would be quite surprised, as i wouldn't even know that code exists from looking at RFC 2616. :) – cHao Mar 04 '13 at 13:53
  • 1
    cHao: you are supposed to look into the IANA status code registry, not RFC 2616. See http://www.iana.org/assignments/http-status-codes/http-status-codes.xml – Julian Reschke Mar 04 '13 at 16:58
  • @JulianReschke: Again, though, that very link points at RFC 4918. The code was made for WebDAV, and i haven't seen anything supporting its use outside that context. – cHao Mar 04 '13 at 17:07
  • @cHao: the link points to RFC 4918 because that's where it is defined. HTTP status codes are extensible; that's why there is a registry. And yes, 422 (and other non-RFC2616 status codes) are used in practice outside WebDAV. – Julian Reschke Mar 04 '13 at 17:26
  • @JulianReschke: You know of a real-world use case for it? I've yet to see a legitimate one; the cases i've seen so far would be better served by 400 or 403. – cHao Mar 04 '13 at 17:38
  • @cHao: anytime you accept JSON or XML request bodies, and they are syntactically correct, but something else within them keeps you from fulfilling the request – Julian Reschke Mar 04 '13 at 17:50
  • @Julian: If the request body is in a form the server is unable to use, it's by definition incorrect. One could easily argue that you're not accepting JSON or XML, but a format *based* on JSON, or XML that validates to a specific schema...and thus, 400 would fit better. But whatever. :) I've changed the main argument against 422, as it's at least arguably useful in other non-this cases. – cHao Mar 04 '13 at 18:28
  • Interestingly, Microsoft thought of this issue and used a non-standard extension on their 404 error for "content-length too large": https://en.wikipedia.org/wiki/HTTP_404#Substatus_codes – cjm Sep 26 '19 at 04:02
  • This thread from W3 also mentions 403 as a suitable response although 507 is also discussed: https://lists.w3.org/Archives/Public/ietf-http-wg/2012AprJun/0316.html – Sergey Dec 28 '20 at 15:10
  • 1
    Since this answer was originally posted, [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231) came out, and changed the wording somewhat. A 400 (Bad Request) became a generic client-side error, and 403 (Forbidden) "indicates that the server understood the request but refuses to __authorize__ it." So in 2022, [Pawel's comment](https://stackoverflow.com/questions/15192477/http-status-code-when-single-request-asks-for-too-large-resource-or-too-many-of#comment125774241_15192477) is correct -- the proper response is a 400 Bad Request. – De117 Oct 14 '22 at 18:19
-4

This should always produce 400 series Client Error. Exactly which error is by choice of the API/CGI developer. I'd expect either a 405, 406, 416 or the 'catch-all' 417. The api developer has control over the text (body) of these error messages to include more useful information.

Jim Black
  • 1,422
  • 1
  • 13
  • 26