Rate Limits & Quotas

Shield implements rate limiting to ensure service stability and fair usage for all users. This page explains the current limits and how to work with them effectively.

Current Rate Limits

Shield uses a combination of IP-based rate limiting and request throttling:

Endpoint	Rate Limit	Period	Notes
/info	60 requests	1 minute	Per IP address
/rpc	30 requests	1 minute	Per IP address

Additionally, there are global transaction processing limits:

Transaction Type	Limit	Period	Notes
Standard transactions	500 MB	1 hour	Combined size of all transactions
Large transactions (>100KB)	50 MB	1 hour	Combined size of large transactions

Rate Limit Response Headers

When making requests to Shield, the following headers are included in responses:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current period
X-RateLimit-Remaining	The number of requests remaining in the current period
X-RateLimit-Reset	The time (in Unix epoch seconds) when the rate limit will reset

Rate Limit Exceeded Response

When you exceed a rate limit, Shield returns a 429 Too Many Requests HTTP status code with a JSON response body:

{
    "error": "Rate limit exceeded",
    "retry_after": 45
}

The retry_after field indicates the number of seconds to wait before making another request.

Best Practices for Working with Rate Limits

Client-Side Rate Limiting

Implement client-side rate limiting to avoid hitting Shield's limits:

// Example rate limiting strategy in JavaScript
class RateLimiter {
    constructor(limit, interval) {
        this.limit = limit;
        this.interval = interval;
        this.requests = [];
    }
    
    canMakeRequest() {
        const now = Date.now();
        // Clean up old requests
        this.requests = this.requests.filter(time => now - time < this.interval);
        // Check if we're under the limit
        return this.requests.length < this.limit;
    }
    
    recordRequest() {
        this.requests.push(Date.now());
    }
}

// Usage
const infoLimiter = new RateLimiter(50, 60000); // 50 requests per minute

async function getShieldInfo() {
    if (!infoLimiter.canMakeRequest()) {
        console.log("Rate limit would be exceeded, waiting...");
        return new Promise(resolve => setTimeout(() => resolve(getShieldInfo()), 2000));
    }
    
    infoLimiter.recordRequest();
    return fetch("https://shield.rebarlabs.io/info");
}

Caching Responses

Cache the /info endpoint response to avoid unnecessary requests:

let shieldInfoCache = {
    data: null,
    timestamp: 0,
    ttl: 5 * 60 * 1000 // 5 minutes TTL
};

async function getShieldInfo() {
    const now = Date.now();
    
    // Return cached data if available and not expired
    if (shieldInfoCache.data && (now - shieldInfoCache.timestamp < shieldInfoCache.ttl)) {
        return shieldInfoCache.data;
    }
    
    // Fetch fresh data
    const response = await fetch("https://shield.rebarlabs.io/info");
    const data = await response.json();
    
    // Update cache
    shieldInfoCache = {
        data,
        timestamp: now,
        ttl: 5 * 60 * 1000
    };
    
    return data;
}

Handling 429 Responses

Implement exponential backoff when you encounter rate limit errors:

async function makeShieldRequest(url, options, retries = 3, baseDelay = 1000) {
    for (let attempt = 0; attempt <= retries; attempt++) {
        try {
            const response = await fetch(url, options);
            
            if (response.status === 429) {
                const data = await response.json();
                const retryAfter = data.retry_after || Math.pow(2, attempt) * baseDelay;
                console.log(`Rate limited. Retrying after ${retryAfter}ms`);
                await new Promise(resolve => setTimeout(resolve, retryAfter));
                continue;
            }
            
            return response;
        } catch (error) {
            if (attempt === retries) throw error;
            const delay = Math.pow(2, attempt) * baseDelay;
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }
}

Transaction Batching

To make the most of your rate limits, consider batching multiple payments into single transactions:

1. Instead of sending 10 separate transactions with 1 recipient each

2. Create 1 transaction with 10 recipients

This approach:

• Reduces the number of API calls needed

• Lowers overall transaction fees

• Makes better use of rate limits

Enterprise Rate Limits

For users with higher volume requirements, Shield offers enterprise-level rate limits and dedicated access. Contact our support team for more information about enterprise options.

Future Changes

Rate limits may change as Shield evolves. These changes will be announced in advance through:

• Updates to this documentation

• Notification on the Shield website

• Email to registered users (when applicable)

Always check the X-RateLimit-* headers in responses to stay aware of current limits.