Configuring PageNumberPagination to raise 404 for out‑of‑range page requests

Django REST Framework (DRF) does not provide a built-in setting to return a 404 response when a requested page number exceeds the total number of available pages. By default, PageNumberPagination returns an empty results list and a 200 OK status.

Implementation via Custom Pagination Class

To enforce a 404 response, you must subclass PageNumberPagination and override the paginate_queryset method. This allows you to validate the requested page against the total count before the queryset is sliced.

from django.http import Http404
from rest_framework.pagination import PageNumberPagination

class StrictPageNumberPagination(PageNumberPagination):
    def paginate_queryset(self, queryset, request, view=None):
        self.request = request
        self.page_size = self.page_size or view.pagination_class.page_size
        
        # Calculate total pages
        count = queryset.count()
        self.count = count
        
        # Extract requested page number
        page_number = request.query_params.get(self.page_query_param)
        
        if page_number:
            try:
                page_number = int(page_number)
                # Calculate total pages based on page_size
                import math
                total_pages = math.ceil(count / self.page_size)
                
                if page_number > total_pages:
                    raise Http404("Page not found")
            except (ValueError, TypeError):
                # Let the base class handle invalid non-integer page numbers
                pass

        return super().paginate_queryset(queryset, request, view)

Applying the Configuration

You can apply this behavior in two ways depending on your API contract requirements:

• Per-View: Set pagination_class = StrictPageNumberPagination within a specific ViewSet or APIView.
• Globally: Update your REST_FRAMEWORK settings in settings.py: 'DEFAULT_PAGINATION_CLASS': 'path.to.StrictPageNumberPagination'.

Behavioral Impact and Trade-offs

Implementing this check affects the API in the following ways:

• Metadata: For valid pages, the count, next, and previous links remain unchanged as the base paginate_queryset logic is still executed.
• Client Expectations: Many API clients expect an empty list as a signal to stop polling. Switching to a 404 may require clients to handle exceptions rather than checking for empty arrays.
• Performance: This approach requires a .count() query on every request. While standard for PageNumberPagination, it can be a bottleneck on extremely large tables without proper indexing.

Verification Steps

1. Request a known valid page (e.g., ?page=1) and verify a 200 OK response with full metadata.
2. Request a page significantly beyond the total count (e.g., ?page=9999) and verify the response is 404 Not Found.
3. Request an invalid page string (e.g., ?page=abc) to ensure the default DRF error handling for invalid parameters still functions.

Diagnostic Detail: Are you using a custom page_size_query_param that allows clients to override the page size? If so, the total_pages calculation must use the dynamic page size from the request instead of the class default.