Pre-release — content may change.

Getting Started

Rate Limits

Understanding and working with Wicket MDP API rate limits

The Wicket MDP API implements rate limiting to ensure fair usage and protect service stability.

Rate Limit Overview

  • Default Limit: 500 requests per minute
  • Enforcement: Per authenticated user or API client
  • Custom Limits: Contact Wicket support if you need higher limits

Monitoring Your Usage

Rate Limit Headers

All API responses include headers to help you monitor your usage:

RateLimit-Limit: 500
RateLimit-Remaining: 499
RateLimit-Reset: 1640995200

Header Descriptions:

HeaderDescription
RateLimit-LimitMaximum requests allowed in the current window
RateLimit-RemainingRequests remaining in the current window
RateLimit-ResetUnix timestamp when the rate limit window resets

Checking Headers in Code

const response = await fetch(`${apiUrl}/people`, {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/vnd.api+json'
  }
});

// Check rate limit headers
const rateLimit = {
  limit: response.headers.get('RateLimit-Limit'),
  remaining: response.headers.get('RateLimit-Remaining'),
  reset: response.headers.get('RateLimit-Reset')
};

console.log(`Remaining: ${rateLimit.remaining}/${rateLimit.limit}`);

// Calculate time until reset
const resetDate = new Date(rateLimit.reset * 1000);
console.log(`Resets at: ${resetDate.toISOString()}`);
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

# Check rate limit headers
rate_limit = {
  limit: response['RateLimit-Limit'],
  remaining: response['RateLimit-Remaining'],
  reset: response['RateLimit-Reset']
}

puts "Remaining: #{rate_limit[:remaining]}/#{rate_limit[:limit]}"

# Calculate time until reset
reset_time = Time.at(rate_limit[:reset].to_i)
puts "Resets at: #{reset_time.iso8601}"

Rate Limit Exceeded

429 Response

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

{
  "errors": [
    {
      "status": "429",
      "code": "rate_limit_exceeded",
      "title": "Too Many Requests",
      "detail": "Rate limit of 500 requests per 60 seconds exceeded",
      "meta": {
        "limit": 500,
        "period": 60,
        "retry_after": 45
      }
    }
  ]
}

Retry-After Header

When rate limited, an additional header indicates when you can retry:

Retry-After: 45

This value is in seconds. Wait this long before making another request.

Best Practices

1. Monitor Rate Limit Headers

Always check the RateLimit-Remaining header to track your usage:

async function fetchWithRateLimitCheck(url) {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/vnd.api+json'
    }
  });

  const remaining = parseInt(response.headers.get('RateLimit-Remaining'));

  if (remaining < 10) {
    console.warn('⚠️  Approaching rate limit!');
  }

  return response.json();
}

2. Implement Exponential Backoff

When you receive a 429 response, retry with exponential backoff:

async function fetchWithRetry(url, maxRetries = 3) {
  let retries = 0;

  while (retries < maxRetries) {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/vnd.api+json'
      }
    });

    // Success
    if (response.status === 200) {
      return response.json();
    }

    // Rate limited
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const waitTime = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.pow(2, retries) * 1000; // Exponential backoff

      console.log(`Rate limited. Waiting ${waitTime}ms...`);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      retries++;
      continue;
    }

    // Other error
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  throw new Error('Max retries exceeded');
}

3. Cache Responses

Reduce redundant API calls by caching responses:

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function fetchWithCache(url) {
  const cached = cache.get(url);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    console.log('📦 Returning cached response');
    return cached.data;
  }

  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/vnd.api+json'
    }
  });

  const data = await response.json();
  cache.set(url, { data, timestamp: Date.now() });

  return data;
}

4. Use Efficient Pagination

Request reasonable page sizes to reduce total API calls:

// ✅ Good: Reasonable page size
const response = await fetch(
  `${apiUrl}/people?page[size]=100`,
  { headers }
);

// ❌ Avoid: Too small, requires many requests
const response = await fetch(
  `${apiUrl}/people?page[size]=10`,
  { headers }
);

See Pagination for more details.

5. Distribute Requests Evenly

Avoid sending bursts of requests. Spread them out over time:

async function processPeopleBatch(peopleIds) {
  const DELAY_BETWEEN_REQUESTS = 200; // 200ms delay

  for (const id of peopleIds) {
    await fetchPerson(id);
    await new Promise(resolve =>
      setTimeout(resolve, DELAY_BETWEEN_REQUESTS)
    );
  }
}

6. Use Bulk Operations

When available, use bulk endpoints instead of individual requests:

// ✅ Good: Single query request with filters
const response = await fetch(
  `${apiUrl}/people/query`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/vnd.api+json'
    },
    body: JSON.stringify({
      filter: {
        uuid_in: [uuid1, uuid2, uuid3, ...]
      }
    })
  }
);

// ❌ Avoid: Multiple individual requests
for (const uuid of uuids) {
  await fetch(`${apiUrl}/people/${uuid}`, { headers });
}

Rate Limit Strategy Example

Here's a complete example combining best practices:

class WicketAPIClient {
  constructor(apiUrl, token) {
    this.apiUrl = apiUrl;
    this.token = token;
    this.cache = new Map();
    this.rateLimitInfo = {
      limit: 500,
      remaining: 500,
      reset: Date.now() + 60000
    };
  }

  async fetch(endpoint, options = {}) {
    // Check if we're close to limit
    if (this.rateLimitInfo.remaining < 10) {
      const waitTime = this.rateLimitInfo.reset - Date.now();
      if (waitTime > 0) {
        console.log(`⏳ Approaching rate limit. Waiting ${waitTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
      }
    }

    const url = `${this.apiUrl}${endpoint}`;
    const response = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/vnd.api+json',
        ...options.headers
      }
    });

    // Update rate limit info
    this.rateLimitInfo = {
      limit: parseInt(response.headers.get('RateLimit-Limit') || 500),
      remaining: parseInt(response.headers.get('RateLimit-Remaining') || 500),
      reset: parseInt(response.headers.get('RateLimit-Reset') || Date.now() + 60000) * 1000
    };

    // Handle rate limiting
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || 60);
      console.warn(`⚠️  Rate limited. Retrying after ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return this.fetch(endpoint, options); // Retry
    }

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return response.json();
  }

  async getPeople(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const endpoint = `/people${queryString ? '?' + queryString : ''}`;
    return this.fetch(endpoint);
  }
}

// Usage
const client = new WicketAPIClient(apiUrl, token);
const people = await client.getPeople({ 'page[size]': 100 });

Need Higher Limits?

If your integration requires higher rate limits, contact Wicket support with:

  • Details about your use case
  • Expected request volume
  • Time distribution of requests

On this page