Rate Limits
Understand API rate limits and how to handle them in your integration.
Overview
The Mployr API implements rate limiting to ensure fair usage and maintain service stability. Rate limits are applied per user and measured using a sliding window.
Rate Limit Tiers
requests per minute
Applies to most API endpoints including People, Documents, Organizations, and other CRUD operations.
requests per minute
Applies to login, registration, password reset, and 2FA endpoints for security purposes.
Rate Limit Headers
Every API response includes headers that indicate your current rate limit status:
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1706468400| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed in the current window |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-RateLimit-Reset | Unix timestamp when the rate limit resets |
Handling Rate Limits
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: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706468400
Retry-After: 45
{
"success": false,
"message": "Too Many Requests",
"retry_after": 45
}Retry-After header for the number of seconds to wait before making another request.Implementing Retry Logic
Here's an example of implementing retry logic with exponential backoff:
async function makeRequestWithRetry(url: string, options: RequestInit, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch(url, options);
if (response.status === 429) {
// Get retry delay from header or use exponential backoff
const retryAfter = response.headers.get('Retry-After');
const delay = retryAfter
? parseInt(retryAfter) * 1000
: Math.pow(2, attempt) * 1000;
console.log(`Rate limited. Retrying in ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
return response;
}
throw new Error('Max retries exceeded');
}Best Practices
Monitor Rate Limit Headers
Check the rate limit headers in every response to proactively manage your request rate and avoid hitting limits.
Implement Exponential Backoff
When retrying failed requests, use exponential backoff to gradually increase the delay between retries.
Cache When Possible
Cache responses for data that doesn't change frequently to reduce the number of API calls.
Batch Requests
When fetching multiple resources, consider using list endpoints with filters rather than individual requests.
Need Higher Rate Limits?
If your integration requires higher rate limits, contact our support team to discuss your use case.