Rate Limits

Rate limits ensure fair usage and optimal performance for all users. Understanding and managing your rate limits is crucial for building reliable applications.

Rate Limits by Plan

Token Bucket Algorithm

Dwellir uses the token bucket algorithm for rate limiting, providing flexible and fair request handling with burst protection.

How It Works

The token bucket algorithm works like a bucket that:

1. Holds tokens - Each token represents permission to make one request
2. Has a maximum capacity - The bucket can hold up to your burst limit
3. Refills at a constant rate - Tokens are added at your plan's responses/second rate
4. Consumes tokens per request - Each API call removes one token

┌─────────────────────────┐
│     Token Bucket        │
│                         │
│  Capacity: 500 tokens   │  ← Burst capacity
│  Current: 350 tokens    │
│  Refill: 100 tokens/s   │  ← Your plan's rate
│                         │
└─────────────────────────┘
         ↓
    API Response
    (consumes 1 token)

Benefits of Token Bucket

1. Burst Handling - Handle traffic spikes gracefully
2. Smooth Rate Limiting - No hard cutoffs at exact intervals
3. Fair Usage - Unused capacity accumulates for later use
4. Predictable Behavior - Easy to understand and plan for

Example Scenarios

Scenario 1: Steady Traffic

• Plan: Developer (100 responses/s)
• Usage: 80 responses/s consistently
• Result: ✅ All requests succeed, 20 tokens/s accumulate up to burst limit

Scenario 2: Traffic Burst

• Plan: Developer (100 responses/s, 500 burst capacity)
• Usage: 300 responses/s for 1 second
• Result: ✅ All requests succeed using burst tokens
• Recovery: Need to stay under 100 responses/s to refill

Scenario 3: Sustained Overuse

• Plan: Developer (100 responses/s)
• Usage: 150 responses/s sustained
• Result: ⚠️ After burst depletes, 50 responses/s are rate limited

Request Counting

What Counts as a Response?

Each of the following counts as 1 API response:

• Standard JSON-RPC calls (eth_getBalance, eth_call, etc.)
• Batch requests count as the number of calls in the batch
• WebSocket messages (both sent and received)
• Even trace and debug methods (no compute unit multipliers!)

Handling Rate Limit Errors

When you exceed your rate limit, you'll receive a 429 HTTP status code with the following response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32005,
    "message": "Rate limit exceeded"
  },
  "id": 1
}

Setting Usage Limits

Protect yourself from unexpected charges by setting limits per API key:

1. Go to dashboard.dwellir.com/api-keys
2. Click the edit icon (✏️) next to your API key
3. Set daily or monthly quotas
4. Click "Update API Key" to save

When a quota is reached, the API will return a 429 error until the quota resets.

Monitoring Your Usage

Dashboard Analytics

Track your usage in real-time at dashboard.dwellir.com/usage:

• Current responses/second
• Daily and monthly usage
• Per-method breakdown
• Geographic distribution

API Access

For programmatic access to usage data, please contact our team.

Need Higher Limits?

If you need higher rate limits:

1. Upgrade Your Plan - Check if a higher tier meets your needs
2. Contact Support - Request custom limits within your current plan
3. Enterprise Solutions - Get custom infrastructure and limits

When requesting increases, provide:

• Current usage patterns
• Expected growth timeline
• Peak traffic requirements
• Use case description

Contact our team for custom rate limits.