Rate Limiting

Understanding and working with API rate limits

Rate Limit Tiers

API rate limits are enforced based on your subscription plan. Each plan includes both per-minute rate limits and monthly quotas.

Plan	Rate Limit	Monthly Quota	Price
Free	10 requests/minute	1,000 requests/month	$0
Basic	60 requests/minute	50,000 requests/month	$29/month
Pro	300 requests/minute	500,000 requests/month	$99/month
Enterprise	Custom (1000+ req/min)	Unlimited	Contact sales

Need Higher Limits?

Enterprise plans offer custom rate limits tailored to your needs.

View Pricing →

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

Response Headerstext

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1707140400
X-RateLimit-Reset-After: 45

Header Descriptions:

X-RateLimit-Limit

Maximum number of requests allowed per minute

X-RateLimit-Remaining

Number of requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the rate limit window resets

X-RateLimit-Reset-After

Number of seconds until the rate limit resets

Handling Rate Limit Errors

When you exceed your rate limit, the API returns a 429 status code with details about when you can retry:

429 Rate Limit Exceeded Responsejson

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 60,
    "reset_at": "2024-02-05T14:00:00Z",
    "reset_after_seconds": 45
  }
}

Important

When rate limited, wait for the duration specified in reset_after_seconds before retrying. Making additional requests will reset the window.

Best Practices

1. Implement Exponential Backoff

When you receive a rate limit error, wait before retrying and increase the wait time for each subsequent failure:

Retry Logic Examplejavascript

import { ShambaRecords } from '@shambarecords/sdk';

const client = new ShambaRecords({
  apiKey: 'sr_pub_your_public_key',
  // Enable automatic retry on rate limit
  retryOnRateLimit: true,
  maxRetries: 3
});

async function fetchPricesWithRetry() {
  try {
    const prices = await client.prices.getLatest({
      product_uuids: ['550e8400-e29b-41d4-a716-446655440000']
    });
    return prices;
  } catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
      const resetAfter = error.details.reset_after_seconds;
      console.log(`Rate limited. Retrying in ${resetAfter} seconds...`);

      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, resetAfter * 1000));

      // Retry the request
      return fetchPricesWithRetry();
    }
    throw error;
  }
}

2. Batch Your Requests

Instead of making multiple individual requests, use endpoints that support batch operations:

Batching Requestsjavascript

// BAD: Making 100 individual requests
for (const productId of productIds) {
  const price = await client.prices.getByUUID(productId);
  // Each call counts against rate limit
}

// GOOD: Batch request with single call
const prices = await client.prices.getLatest({
  product_uuids: productIds, // Pass all IDs at once
  limit: 100
});

3. Implement Caching

Cache API responses to reduce the number of requests you need to make:

Caching Strategyjavascript

import NodeCache from 'node-cache';

const cache = new NodeCache({ stdTTL: 300 }); // 5 minute cache

async function getCachedPrices(productUUID) {
  const cacheKey = `prices_${productUUID}`;

  // Check cache first
  const cached = cache.get(cacheKey);
  if (cached) {
    console.log('Returning cached data');
    return cached;
  }

  // Fetch from API if not cached
  const prices = await client.prices.getLatest({
    product_uuids: [productUUID]
  });

  // Store in cache
  cache.set(cacheKey, prices);

  return prices;
}

4. Monitor Your Usage

Track your API usage in the dashboard to understand your patterns and avoid hitting limits:

View Usage Dashboard →

Additional Tips

✓ Use webhooks for real-time updates

Instead of polling endpoints frequently, use webhooks to receive updates when data changes.

✓ Request only the data you need

Use filters and pagination parameters to limit response sizes and reduce the number of requests needed.

✓ Respect rate limit headers

Always check the rate limit headers in responses and adjust your request rate accordingly.

✓ Use the appropriate authentication level

Public key requests have the same rate limits as secret key requests, but secret keys give you access to more endpoints.