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: 1640995200Header Descriptions:
| Header | Description |
|---|---|
RateLimit-Limit | Maximum requests allowed in the current window |
RateLimit-Remaining | Requests remaining in the current window |
RateLimit-Reset | Unix 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: 45This 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