Exceeded limit for API pagination

Question

I'm implementing an API with pagination which has max_results that can be specified by the client. The server will have a hardcoded limit, for example 100 results per page.

In the situation when the client specify max_results >100 which is more expected behaviour and why do you think so:

• return just 100
• raise an error with a message that the server cannot handle more than 100 per page
• other solution?

Answer 1

In general, explicit errors are good. But for the specific issue of a pagination limit, silent truncation of the result is probably better.

• This is not really a fatal error – you will still be returning data.
• The client can issue multiple requests until they have received as much data as they need.
• This allows you to document the limit as an upper bound on the returned values, while giving you the freedom to return fewer results.
• For example, you can then change the limit without notice, possibly even dynamically.

It would still be a good idea to notify the client when they requested more elements than they will ever get. For example, your API might return a JSON object that's either {"data": [...]} or {"error": ...}. In either case, you could add a "warning": ..." entry. But that only makes sense for public API. When an API is only used internally, it's probably sufficient to silently ignore the issue (hoping that other communication channels will explain the limitation) or to at least log it for review.