Rate Limits

The Web3.Market API enforces rate limits on all endpoints to ensure fair usage and protect the service from abuse. Rate limits are applied per API key using a sliding window algorithm.

Limits per Tier

Rate limits are determined by the tier associated with your API key. When you upgrade your plan, the higher limits take effect immediately for all active keys.

Sliding Window Algorithm

The rate limiter uses a sliding window approach rather than fixed time buckets. This means your request count is calculated over a rolling 60-second window (for per-minute limits) and a rolling 24-hour window (for daily limits).

For example, if your per-minute limit is 30 and you send 30 requests between 12:00:00 and 12:00:30, you cannot send any more requests until 12:01:00 when the earliest requests begin falling out of the window.

Rate Limit Headers

Every API response includes rate limit headers so you can track your current usage:

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
Content-Type: application/json

Rate Limit Exceeded Response

When you exceed the rate limit, the API returns a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 34
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later."
  }
}

The Retry-After header tells you how many seconds to wait before the rate limit window resets.

Best Practices

Implement Exponential Backoff

If you receive a 429 response, wait for the duration specified in the Retry-After header before retrying. For subsequent retries, use exponential backoff:

async function fetchWithBackoff(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, { headers });
 
    if (response.status !== 429) {
      return response;
    }
 
    if (attempt === maxRetries) {
      throw new Error('Rate limit exceeded after maximum retries');
    }
 
    const retryAfter = parseInt(
      response.headers.get('Retry-After') || '60',
      10
    );
    const backoff = retryAfter * 1000 * Math.pow(2, attempt);
    await new Promise(resolve => setTimeout(resolve, backoff));
  }
}

Monitor Your Usage

Check the X-RateLimit-Remaining header in API responses to understand your current consumption. If the remaining count is consistently low, consider reducing your request frequency or upgrading your plan.

Cache Responses Where Possible

Cache responses for read-heavy endpoints like template listings. Template data does not change frequently, so a cache TTL of a few minutes can significantly reduce your request count.