Skip to main content
The ShingleAI API enforces rate limits to ensure fair usage and maintain service stability for all users. Rate limits vary by subscription tier.

​
Rate Limits by Tier

TierRequests per MinuteBurst Limit
Free1015
Starter3045
Pro100150
EnterpriseCustomCustom
Burst limits allow temporary spikes above your per-minute limit. For example, a Pro tier user (100 req/min) can make up to 150 requests in a short burst. However, sustained traffic above your base rate limit will result in throttling. Burst capacity refills as your request rate drops below the limit.

​
Rate Limit Headers

Every API response includes headers to help you track your rate limit status:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (in seconds) when the rate limit resets
Example response headers: 
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1701388800
Content-Type: application/json

​
Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests response: 
{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Rate limit exceeded. Please retry after 60 seconds",
        "details": {
            "retryAfter": 60
        }
    }
}
The response includes a Retry-After header indicating how many seconds to wait before retrying.

​
Implementing Rate Limit Handling

async function fetchWithRateLimit(url: string, options: RequestInit) {
    const response = await fetch(url, options);

    // Check remaining quota
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
    const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0');

    if (remaining < 5) {
        console.warn(`Rate limit low: ${remaining} requests remaining`);
    }

    // Handle rate limiting
    if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        console.log(`Rate limited. Waiting ${retryAfter} seconds...`);

        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        return fetchWithRateLimit(url, options); // Retry
    }

    return response;
}

​
Best Practices

Instead of making requests as fast as possible, implement a queue that spreads requests evenly across your rate limit window.
class RequestQueue {
    private queue: Array<() => Promise<void>> = [];
    private processing = false;
    private requestsPerSecond: number;

    constructor(requestsPerMinute: number) {
        this.requestsPerSecond = requestsPerMinute / 60;
    }

    async add<T>(fn: () => Promise<T>): Promise<T> {
        return new Promise((resolve, reject) => {
            this.queue.push(async () => {
                try {
                    resolve(await fn());
                } catch (e) {
                    reject(e);
                }
            });
            this.process();
        });
    }

    private async process() {
        if (this.processing) return;
        this.processing = true;

        while (this.queue.length > 0) {
            const fn = this.queue.shift()!;
            await fn();
            await new Promise(r =>
                setTimeout(r, 1000 / this.requestsPerSecond)
            );
        }

        this.processing = false;
    }
}
Track X-RateLimit-Remaining proactively. When it drops below a threshold, slow down your request rate before hitting the limit.
When you receive a 429 response, don’t immediately retry. Use the Retry-After header value, or implement exponential backoff starting at 1 second.
Reduce API calls by caching responses that don’t change frequently. This is especially useful for reference data like contact lists or business details.
Where available, use batch endpoints to perform multiple operations in a single request instead of making separate calls.

​
Increasing Your Limits

If you consistently need higher rate limits:
  1. Upgrade your plan - Higher tiers include increased rate limits
  2. Contact sales - Enterprise plans include custom rate limits tailored to your needs

Upgrade Your Plan

View pricing and upgrade options