Correct HTTP status code to number of items per page exceeded + pagination offset

Question

I have a restriction in my API where the maximum permitted number of items per page is 50.

What is the correct HTTP code to return to consumer if he put 51, for example?

I thought about HTTP 400 (Bad request), because the consumer "knows" (based in API conventions) that the maximum is 50. In this case I will also return a response with the error described.

The same question for pagination. If I have 20 rows/objects and the API consumer put 21 in the offset param, should I return HTTP 200 with total = 0?

Answer 1

This definitely falls into the 4XX categories of HTTP response.

For the first scenario:

I think the post appropriate status for this use case is 400 BAD REQUEST, based on the HTTP spec (https://www.rfc-editor.org/rfc/rfc7231#section-6.5.1)

6.5.1. 400 Bad Request

The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

The user "knows" that API will not accept > 50 and the server will/would try to fulfil the another request that conforms with the rules of your API.

For the second scenario:

I'm not sure if understood that correctly.

200 OK would be correct if your API shows all 20 rows/objects instead of silently saying that the request succeed and there's no objects at all!

However:

You might consider 404 Not Found depending on your business rules if the page 21 does not exist.

From RFC7231 :

The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.

---

Maybe you could explain more the second scenario and I'll edit the response accordingly :)

Answer 2

Let's suppose you are working with offset and limit in the request and count (and perhaps total) in the response. You ask for a maximum number of results (limit) skipping n results from the beginning (offset) and in the response you get the items, and the number of items returned (to facilitate automation).

The first scenario should not be an error. It is the same case as the last page (they ask for 50 but you only return remaining).

• You should return HTTP 200 and the field count=50 or the number of records returned.

The second scenario could return one of these:

• HTTP 200 with count=0 (total must be allways the same) and no items in the returned list.
• HTTP 400 because invoker asked for an url that is invalid
• HTTP 404 because items to return are not found

I think it's safe to return an error (4xx + error info) in this situation because the offset can be exceeded by one of these assumptions:

• A coding error
• Invoker is not fetching data from begining (no fresh state)
• Invoker ignored pagination data (present on each response)
• You are not using total field in the response (which is optional because there are some situations where you can not count all items or simply it's very expensive counting them). In this case, if your last page has the same number of items (count) as the number of items asked for in the request (limit), there is no way to know that this is the last page, so you try another one. In that last request you will get a count=0 in the response and you can stop asking for pages. This case makes it fair to return a 200 code also because the programmer did exactly what you asked for in the API documentation.