API Throttling

The API throttling enforces rate limits to prevent abuse, protect resources, and ensure fair usage. This mechanism helps maintain a stable API by restricting excessive requests from users or automated systems.

Table of Contents

1. Overview
2. Throttling Rules & Rate Limits
3. How Throttling Works
   3.1 Throttle Enforcement Process
   3.2 Throttle Scopes in Views
4. Handling a Throttled Request
   4.1 Error Response
   4.2 What Should the User Do?
   4.3 Troubleshooting Throttling Issues

1. Overview

• Throttling applies to all API endpoints and is based on user authentication status and request type.
• Limits are defined per minute, with different thresholds for:
  • Unauthenticated users (stricter limits to prevent bot abuse).
  • Authenticated users (higher limits for regular interaction).
  • File management operations (uploads and deletions).
  • User management actions (logins, password resets, etc.).
• If a user exceeds the allowed rate, the system responds with a 429 Too Many Requests error.

---

2. Throttling Rules & Rate Limits

• The API defines throttling rules in settings.py:

  REST_FRAMEWORK = {
      'DEFAULT_THROTTLE_RATES': {
          'anon': '5/min',
          'user': '100/min',
          'wallconfig-files-management': '5/min',
          'user-management': '10/min',
      }
  }

  
  

• Throttle rules breakdown:

  Throttle Scope	Rate Limit	Applies To
  Unauthenticated anon	5 requests/min	API calls from non-logged-in users.
  Authenticated user	100 requests/min	API calls from logged-in users with valid authentication.
  File Management wallconfig-files-management	5 requests/min	Uploading and deleting wall configuration files.
  User Management user-management	10 requests/min	Login attempts, password resets, and account modifications.

Notes

🗒️ Unauthenticated and authenticated request counts are tracked separately.

🗒️ If a user logs in, their request rate is upgraded to the authenticated limit.

🗒️ Throttling does not reset when switching between scopes. It dynamically adjusts based on authentication status.

💡 Throttle scopes are assigned based on the API endpoint.
The full mapping of endpoints to their respective throttle limits can be found in the API Access Overview page.

Return to Top

---

3. How Throttling Works

The Wall API leverages DRF throttling classes to manage request rates dynamically.
The system assigns a throttle scope to each endpoint, allowing fine-grained control over request limits.

3.1 Throttle Enforcement Process

graph TD
    A[Request Received] -->|Determine Throttle Scope| B[Throttle Scope Assigned]
    B -->|Proceed| C[Check Current Usage]
    C -->|Within Limit| D[Process Request Normally]
    C -->|Exceeds Limit| E[Block Request]
    E -->|Return 429 Too Many Requests| F[Notify User]

    style A fill:#8E44AD,stroke:#FFFFFF,stroke-width:2,rx:10,ry:10,color:#FFFFFF;
    style B fill:#415A77,stroke:#ECF0F1,stroke-width:2,rx:10,ry:10,color:#ECF0F1;
    style C fill:#1976D2,stroke:#FFFFFF,stroke-width:2,rx:10,ry:10,color:#FFFFFF;
    style D fill:#27AE60,stroke:#FFFFFF,stroke-width:2,rx:10,ry:10,color:#FFFFFF;
    style E fill:#F1C40F,stroke:#FFFFFF,stroke-width:2,rx:10,ry:10,color:#FFFFFF;
    style F fill:#E67E22,stroke:#FFFFFF,stroke-width:2,rx:10,ry:10,color:#FFFFFF;

Loading

Return to Top

3.2 Throttle Scopes in Views

• Throttle scopes are applied in API views using throttling.ScopedRateThrottle and UserRateThrottle:

  • throttle_classes → Defines the applied throttling strategy (e.g., user-based, anonymous-based, or scoped).
  • throttle_scope → Maps the view to a specific rate limit defined in settings.py.

• All views that use the ScopedRateThrottle class explicitly define a throttle_scope.

• Views using the UserRateThrottle class have no defined throttle_scope, which means:

  • Authenticated users are limited to the Authenticated scope (100 requests per minute).

  • Anonymous users are limited to the Unauthenticated scope (5 requests per minute).

    🗒️Unlike ScopedRateThrottle, where omitting a throttle_scope results in no throttling, UserRateThrottle always enforces a rate limit based on authentication status. This effectively acts as a built-in fallback, ensuring that requests are still rate-limited even when no explicit scope is assigned.

  
  

• Example, in WallConfigFileDeleteView:

  • throttle_classes enables scoped throttling

  • and throttle_scope assigns the wallconfig-files-management rate limit:

    class WallConfigFileDeleteView(APIView):
        throttle_classes = [ScopedRateThrottle]
        throttle_scope = 'wallconfig-files-management'

    
    

• Scoped throttling allows fine-grained control, where each API view can have custom rate limits defined centrally in settings.py.

Return to Top

---

4. Handling a Throttled Request

4.1 Error Response

• When a user exceeds the limit, the API responds with a 429 Too Many Requests error:

  {
      "error": "Request was throttled. Expected available in 53 seconds."
  }

4.2 What Should the User Do?

  ✔ Space out requests – Avoid making too many calls in a short period.
  ✔ Implement exponential backoff – If throttled, wait longer before retrying.
  ✔ Use authentication – Logged-in users have higher rate limits.

💡 Best Practice: If your application needs frequent API requests, implement caching or batch requests to reduce redundant calls.

4.3 Troubleshooting Throttling Issues

• Monitor API responses – Look for 429 Too Many Requests errors.
• Check the response headers – DRF includes the rate-limit header retry-after in throttled responses.
• Adjust client request intervals – Reduce request frequency programmatically.

💡 Throttling rules in settings.py should be modified after careful testing to avoid excessive server load.

---

Next:   Environment Variables Index
Back to: Message Themes

Return to Top
DTS Index
Home Page

---