What is Rate Limiting?
Automater uses a sophisticated token bucket system to protect your Discord server from automation overload. Think of it as a “work budget” that prevents your bot from overwhelming Discord’s API or your server with too many actions at once.Token System
Multi-scope token buckets that measure and limit work across different dimensions.
Queue Management
Intelligent queueing with ETA-based admission control and fair scheduling.
Dashboard Metrics
Real-time monitoring of rate limits, queues, and system performance.
Policy Configuration
Three preset policies: Conservative, Balanced, and Aggressive configurations.
How It Works
Core Concepts
Tokens = Work Units
Tokens = Work Units
Every automation action costs tokens based on complexity:
- Send message = 1 token
- Add/remove role = 2 tokens
- Kick/ban user = 3-5 tokens
- Create/delete channel = 10-15 tokens
Multiple Token Buckets
Multiple Token Buckets
Rate limiting operates across 5 different scopes:
- Global: All servers using Automater
- Guild: Your specific Discord server
- User: Individual users (prevents spam)
- Flow: Specific automations (prevents runaway workflows)
- Action Type: Categories like messaging, moderation, etc.
Reserve → Execute → Refill
Reserve → Execute → Refill
- Reserve: Check if all buckets have enough tokens
- Execute: Run the automation if tokens available
- Refill: Tokens automatically restore over time
Token Bucket System
Visual Representation
Bucket Scopes Explained
| Scope | Purpose | Example Limits |
|---|---|---|
| Global | Protect entire platform | 10,000 tokens/minute |
| Guild | Protect your server | 150 tokens/minute |
| User | Prevent user spam | 8 tokens/10 seconds |
| Flow | Control automation rate | 80 tokens/minute |
| Action Type | Limit action categories | 40 HTTP requests/minute |
Action Token Costs
Token costs reflect the “weight” of each action on Discord’s API and your server’s performance.
| Action Category | Examples | Token Cost |
|---|---|---|
| Light Actions | Send text, simple DB read | 0.5-1 tokens |
| Medium Actions | Send embed, add role, variable update | 1-2 tokens |
| Heavy Actions | Kick/ban, timeout, HTTP request | 3-4 tokens |
| Administrative | Create/delete channels, roles | 5-15 tokens |
Policy Presets
Choose from three pre-configured rate limiting policies based on your server’s needs:Conservative Policy
Best for: Small servers, testing, or when stability is paramount- Guild limit: 60 tokens/minute (1 token/second refill)
- Queue threshold: 5 seconds
- Concurrency: 4 flows maximum
Balanced Policy ⭐ (Recommended)
Best for: Most servers with moderate automation usage- Guild limit: 150 tokens/minute (2.5 tokens/second refill)
- Queue threshold: 15 seconds
- Concurrency: 12 flows maximum
- Action limits: 80 messages, 40 embeds, 30 role edits per minute
Aggressive Policy
Best for: Large, active servers with heavy automation needs- Guild limit: 240 tokens/minute (4 tokens/second refill)
- Queue threshold: 30 seconds
- Concurrency: 16 flows maximum
Queue & Throttling System
When Automations Queue vs. Throttle
Queue (Wait briefly):- ETA ≤ 15 seconds (Balanced policy)
- System can handle the wait
- Fair scheduling ensures no automation starves others
- ETA > 15 seconds (would take too long)
- Queue is full (too many waiting)
- Emergency system protection triggered
Queue Fairness
The system uses Weighted Fair Queuing to ensure no single automation monopolizes resources:Dashboard Integration
Real-Time Monitoring
The dashboard provides live visibility into your rate limiting status: KPI Cards:- Runs: Total automation executions
- Throttled: Actions blocked by rate limits
- Queue Wait: Average time automations spend queued
- Tokens Used: Current token consumption
- Guild bucket fill level and refill rate
- Per-action type usage bars
- Queue depth and estimated wait times
- Recent throttling events with reasons
Interpreting the Metrics
Healthy Usage Patterns
Healthy Usage Patterns
✅ High Runs + Low Throttled = Healthy heavy usage
✅ Steady token consumption = Consistent automation activity
✅ Short queue waits = System handling load well
Warning Signs
Warning Signs
⚠️ High Throttled count = Check which bucket is limiting
⚠️ Guild bucket near full = Consider raising capacity or optimizing flows
⚠️ Action type bars pegged = Specific action category saturated
Critical Issues
Critical Issues
🔴 Persistent throttling = Need to optimize automations or raise limits
🔴 Queue wait increasing = Consider raising concurrency
🔴 Action types constantly maxed = Raise specific action limits
Common Rate Limiting Scenarios
Example 1: Welcome Message Surge
Scenario: 80 new members join in 1 minute- Each welcome costs 2 tokens (message + DB write)
- Total needed: 160 tokens
- Guild bucket capacity: 150 tokens
- Result: First 75 welcomes execute immediately, last 5 queue for ~4 seconds
Example 2: Moderation Action Burst
Scenario: Mass ban operation (30 users)- Each ban costs 7 tokens (timeout + log + DM)
- Moderation action limit: 20/minute
- Result: First 20 execute, remaining 10 throttled with reason “actionType:moderation”
Troubleshooting Rate Limits
Common Issues & Solutions
| Problem | Likely Cause | Solution |
|---|---|---|
| ”Guild minute limit” errors | Heavy automation activity | Spread out triggers or raise guild capacity |
| ”Action type limit” errors | Too many of one action type | Increase specific action limits |
| ”Queue full” errors | System overloaded | Reduce automation frequency or raise concurrency |
| High queue wait times | Insufficient processing capacity | Optimize automations or raise concurrency limit |
Optimization Strategies
- Reduce Action Weights: Combine multiple light actions instead of heavy ones
- Spread Triggers: Avoid burst patterns, use delays between actions
- Optimize Workflows: Remove unnecessary actions, use conditions to filter
- Monitor Patterns: Use dashboard metrics to identify bottlenecks
Next Steps
- Token System Details - Deep dive into bucket mechanics
- Queue Management - Understanding fairness and scheduling
- Dashboard Metrics - Master the monitoring interface
- Error Codes - Handle rate limiting errors gracefully