32

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

An anonymous client requests a range of items from a collection via a RESTful API. The client uses GET method with some range parameters, for example GET /collection/?range_start=100&range_end=200. The OK response from the server contains a list of 100 items in JSON. Also, the server has a limit for the number of items the client can request, let's say 300. What should the response status code be if the client wants too many items, for example thousand items in the range [100, 1100]? That is 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

Improve this question
1
  • 1
    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. Commented Feb 17, 2022 at 3:00

4 Answers 4

Reset to default
29

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

Improve this answer
Sign up to request clarification or add additional context in comments.

11 Comments

No, 422 is not specific to WebDAV. But it is indeed not the right status here.
@JulianReschke: Status code 422 is defined in RFC 4918, 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: you are supposed to look into the IANA status code registry, not RFC 2616. See iana.org/assignments/http-status-codes/http-status-codes.xml
@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.
Since this answer was originally posted, RFC 7231 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 is correct -- the proper response is a 400 Bad Request.
|
1

What about 507?

507 Insufficient Storage (WebDAV; RFC 4918)

The server is unable to store the representation needed to complete the request.

This would be illustrative of "result is too big to handle" without risking a false positive for 409.

Improve this answer

1 Comment

Indeed, a requested or uploaded resource can be so large that its computed and encoded representation does not fit to the memory or even storage available for the server. The memory limits are set by the operating system and the hardware, and in the end, a human maintainer. Docker and alike may set virtual limits for the container processes. The request exceeding these limits by accident is likely worth HTTP 507. However, the 500s generally instruct the server developer to improve the code to prevent the crashes or avoid reaching the hard limits again, while the 400s instruct the client.
0

What about 429:

from https://en.wikipedia.org/wiki/List_of_HTTP_status_codes

429 Too Many Requests (RFC 6585) The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.[24]

Improve this answer

1 Comment

Intriguing. However, as the description says, the 429 is for rate limiting. It concerns the frequency of requests and therefore implies that 1) there is nothing wrong with the request but 2) the client should wait some time before the next attempt. In the context of the question, the client cannot solve the issue by waiting but needs to modify the request to meet the requirements set by the server. Thus 429 would be misleading.
-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.

Improve this answer

1 Comment

No, 417 is not "catch all". It has a very specific use case.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.