JSON REST Api Pagination page out of bounds or empty collection response code

Question

Looking for some best practices please...

Scenario 1: GET: /api/v1/widgets/?page=10&per_page=5 The widgets collection only contains 10 records. So the page is out of bounds.

Scenario 2: GET: /api/v1/widgets/ The widgets collection is currently empty.

So in both scenarios, I am looking for an appropriate status code and response.

My thoughts:

• 422 unprocessable entity Normally used for validation, however in this case, I think it would be appropriate because the page requested is out-of-bounds. Particularly useful for scenario 1
• 400 bad request Because the page is out-of-bounds: Scenario 1
• 404 Not found Because the resource is empty: Scenario 1 & 2
• 204 No ContentBecause both collections return empty data: Scenarion 1 & 2
• 200 - with data as empty array because url is valid, but content is non-existent. Scenarios 1 & 2

Is there a current best-practice for this structure?

Answer 1

I suggest to return an empty collection and status code 200. In addition, you should provide hyperlinks in the response header to point clients to "correct" pages, for example the first page or the last "valid" page. For paging of collection resources, the server should always respond with hyperlinks to previous and next pages.