Rate Limits & Quotas

This guide explains TheRPC's rate limiting system and provides best practices for managing your API usage.

# Request Limits

Rate limits are applied at several levels:

Requests per second
Requests per minute
Requests per day
Concurrent connections

Specific limits depend on your subscription plan. Check your dashboard for current limits.

# Error Responses

When you exceed rate limits, you'll receive:

1{
2	"jsonrpc": "2.0",
3	"error": {
4		"code": -32029,
5		"message": "Rate limit exceeded"
6	},
7	"id": 1
8}

HTTP response will include headers:

1X-RateLimit-Limit: 10
2X-RateLimit-Remaining: 0
3X-RateLimit-Reset: 1628696400

# Best Practices

Implement Retries

1async function callWithRetry(method, params, maxRetries = 3) {
2	for (let i = 0; i < maxRetries; i++) {
3		try {
4			const response = await makeRequest(method, params);
5			return response;
6		} catch (error) {
7			if (error.code === -32029) {
8				// Rate limit exceeded
9				const backoffTime = Math.pow(2, i) * 1000;
10				await new Promise((resolve) => setTimeout(resolve, backoffTime));
11				continue;
12			}
13			throw error;
14		}
15	}
16	throw new Error('Max retries exceeded');
17}

Batch Requests

Combine multiple calls into a single request:

1[
2	{
3		"jsonrpc": "2.0",
4		"method": "eth_getBalance",
5		"params": ["0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "latest"],
6		"id": 1
7	},
8	{
9		"jsonrpc": "2.0",
10		"method": "eth_blockNumber",
11		"params": [],
12		"id": 2
13	}
14]

Use WebSocket Subscriptions

For real-time data, use eth_subscribe instead of polling.

# Monitoring

Monitor your usage through:

Dashboard metrics
Rate limit headers
Usage alerts

# Quota Management

Track Usage

1function trackApiUsage(response) {
2	const limits = {
3		limit: response.headers['X-RateLimit-Limit'],
4		remaining: response.headers['X-RateLimit-Remaining'],
5		reset: response.headers['X-RateLimit-Reset'],
6	};
7 
8	// Log or monitor usage
9	console.log(`API calls remaining: ${limits.remaining}/${limits.limit}`);
10}

Implement Caching

1const cache = new Map();
2 
3async function getCachedBlockNumber(cacheTime = 5000) {
4	const cached = cache.get('blockNumber');
5	if (cached && Date.now() - cached.timestamp < cacheTime) {
6		return cached.value;
7	}
8 
9	const newValue = await web3.eth.getBlockNumber();
10	cache.set('blockNumber', {
11		value: newValue,
12		timestamp: Date.now(),
13	});
14 
15	return newValue;
16}

# Plan Limits

Different subscription plans have different limits:

Base Limits

Request rate
Daily quota
WebSocket connections
Subscription limits

Additional Features

Archive data access
Debug methods
Trace API

Check the pricing page for detailed plan comparisons.

# Upgrade Options

If you regularly hit rate limits, consider:

Optimizing your requests
Implementing caching
Using WebSocket subscriptions
Upgrading your plan

# Error Prevention

Monitor Usage

Track request counts
Set up alerts
Review usage patterns

Optimize Requests

Batch when possible
Cache responses
Use appropriate polling intervals