Djangothrottling

When you build and deploy a public-facing web API using Django and Django REST Framework (DRF), your endpoints are suddenly exposed to the open internet. While this openness is essential for growth, it also opens the door to severe risks: continue reading this malicious scrapers harvesting your database, automated scripts brute-forcing login endpoints, buggy client applications flooding your server with endless loops, and distributed denial-of-service (DDoS) attacks.

Without traffic control, a single misbehaved client can monopolize your server resources, causing database locks, memory exhaustion, and sluggish performance for all other users.

The definitive solution to this vulnerability is Throttling (often referred to as rate limiting).

In this comprehensive guide, we will explore how throttling works in Django REST Framework, examine built-in rate-limiting classes, walk through code implementations, build custom tier-based throttles, and review production best practices.

What is API Throttling?

Throttling is the process of restricting the number of requests a client can make to an API within a specified time window. When a client exceeds this allocated quota, the server intercepts the request and rejects it with an HTTP 429 Too Many Requests status code.

Unlike authentication (which verifies who you are) or permissions (which verify what you are allowed to do), throttling regulates how often you are allowed to act.

Behind the scenes, DRF’s throttling system relies on Django’s cache backend (such as Redis or Memcached) to track request timestamps, associating them with either an anonymous user’s IP address or an authenticated user’s primary key.

The Built-in DRF Throttling Classes

Django REST Framework comes with several built-in throttling classes out of the box, designed to handle common traffic management scenarios.

1. `AnonRateThrottle`

This limits the rate of API requests made by unauthenticated users. It identifies clients using their IP address.

Use Case: Protecting public endpoints (like article lists or search bars) from anonymous scrapers.

2. `UserRateThrottle`

This limits requests made by authenticated users. It identifies users by their unique user ID, meaning the rate limit applies across all devices and IP addresses the user logs in from.

Use Case: Enforcing standard user quotas for general API usage.

3. `ScopedRateThrottle`

This allows you to apply different throttle rates to specific views or individual actions within a single ViewSet using a string identifier called a scope.

Use Case: Applying strict rate limits to resource-heavy endpoints (such as a PDF report generator or password reset) while keeping looser limits for standard CRUD operations.

Step-by-Step Implementation

Let’s look at how to configure and apply throttling in a Django project.

Step 1: Configure the Cache Backend

Because throttling tracks request counts dynamically in memory, you must configure a cache backend in your settings.py. Using locmem (local memory cache) is fine for local development, but production environments require Redis or Memcached.

Python

# settings.py
CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379/1',
    }
}

Step 2: Set Global Default Throttles

You can configure global throttling rules that apply to see this website every endpoint across your entire project by adding DEFAULT_THROTTLE_CLASSES and DEFAULT_THROTTLE_RATES to your REST_FRAMEWORK settings:

Python

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',     # Anonymous users: 100 requests per day
        'user': '1000/day',    # Authenticated users: 1,000 requests per day
    }
}

Supported Rate Duration Strings

DRF supports flexible rate strings using the format number/period, where the period can be s (second), m (minute), h (hour), or d (day).

'10/min' -> 10 requests per minute
'5/sec' -> 5 requests per second
'1000/day' -> 1,000 requests per day

Applying View-Level and Scoped Throttling

Global throttles are great for baseline protection, but different endpoints require tailored limits. You can override or customize throttling directly on individual ViewSets.

1. Using Scoped Rate Throttling

Imagine you have an article ViewSet, but you want to heavily restrict how often users can export articles to PDF to prevent server strain.

First, define the scope rate in your settings:

Python

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day',
        'exports': '5/hour', # Custom scope rate
    }
}

Next, apply the ScopedRateThrottle to your custom action:

Python

# views.py
from rest_framework import viewsets
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.throttling import ScopedRateThrottle
from .models import Article
from .serializers import ArticleSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer

    @action(detail=True, methods=['get'], throttle_classes=[ScopedRateThrottle])
    def export_pdf(self, request, pk=None):
        self.throttle_scope = 'exports' # Links to 'exports' rate in settings
        article = self.get_object()
        # Heavy PDF generation logic here...
        return Response({'status': f'PDF generated for article {article.id}'})

Writing Custom Throttles for Tiered Subscriptions

Standard user rate throttling applies a flat limit to everyone. However, modern SaaS applications often require tiered rate limiting—for instance, Free tier users get 100 requests per hour, while Premium subscribers get 10,000 requests per hour.

You can achieve this by subclassing DRF’s UserRateThrottle:

Python

# throttles.py
from rest_framework.throttling import UserRateThrottle

class TieredUserRateThrottle(UserRateThrottle):
    def get_rate(self):
        # Check if the user is authenticated and has a subscription tier
        if self.request.user and self.request.user.is_authenticated:
            if hasattr(self.request.user, 'profile') and self.request.user.profile.is_premium:
                return '10000/hour' # Premium user limit
            return '500/hour'     # Standard authenticated user limit
        
        return '100/hour'         # Fallback for anonymous users

To use your custom throttle, register it inside your ViewSet:

Python

# views.py
from .throttles import TieredUserRateThrottle

class PremiumArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    throttle_classes = [TieredUserRateThrottle]

Summary Comparison: Throttling Classes

Throttle Class	Identification Basis	Best Used For	Configuration Scope
`AnonRateThrottle`	IP Address	Public endpoints, login pages, registration forms.	Global or View-level
`UserRateThrottle`	User ID (Primary Key)	Standard authenticated API resources.	Global or View-level
`ScopedRateThrottle`	User ID or IP + Scope Name	Specific high-cost actions (reports, exports, AI prompts).	View-level action
`Custom Throttles`	Dynamic logic (Roles, Tiers, Plans)	SaaS platforms with tiered subscription models.	View-level

Production Best Practices

Always Use Redis in Production: Never rely on Django’s default local-memory cache (LocMemCache) for throttling in a multi-server or multi-process production deployment (like Gunicorn/Uwsgi workers). Local memory is isolated per worker process, meaning a user can bypass rate limits simply by hitting different worker instances. Always use a centralized Redis cache.
Include Rate Limit Headers: Inform clients of their current quota status by including standard rate-limiting headers in your API responses (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). This allows frontend apps to handle rate limits gracefully before hitting a 429 error.
Exclude Trusted IPs: If your frontend application communicates with your backend via a shared server IP or webhook provider (like Stripe or GitHub), make sure to bypass throttling for those specific trusted IPs so external integrations don’t break unexpectedly.

Conclusion

API throttling is an indispensable pillar of building secure, resilient, and enterprise-ready Django applications. By leveraging Django REST Framework’s flexible throttling backends—whether through standard IP checks, see authenticated user quotas, scoped action limits, or custom tiered subscription rules—you protect your infrastructure from abuse and ensure high availability for all legitimate users.

What is API Throttling?

The Built-in DRF Throttling Classes

1. AnonRateThrottle

2. UserRateThrottle

3. ScopedRateThrottle

Step-by-Step Implementation

Step 1: Configure the Cache Backend

Step 2: Set Global Default Throttles

Supported Rate Duration Strings

Applying View-Level and Scoped Throttling

1. Using Scoped Rate Throttling

Writing Custom Throttles for Tiered Subscriptions

Summary Comparison: Throttling Classes

Production Best Practices

Conclusion

1. `AnonRateThrottle`

2. `UserRateThrottle`

3. `ScopedRateThrottle`