Rate Limits

The Lindris API implements rate limiting to ensure fair usage and protect the platform from abuse. All API endpoints are subject to these rate limits.

Default Limits

All API endpoints enforce two independent rate limits that work together:

1. 60 requests per minute (per user for authenticated, per IP for unauthenticated)
2. 2 requests per second sustained rate

Both limits must be satisfied for requests to succeed. This dual approach:

• Allows reasonable burst traffic (e.g., fetching paginated data quickly)
• Prevents sustained high-frequency requests that could impact platform performance

Planning High-Volume Integrations?

If you need to send thousands of requests in a short burst (e.g., syncing active customers), contact our support team to discuss temporarily increasing your rate limits.

How Rate Limiting Works

Authenticated Requests

When you make authenticated API requests using your API key, rate limits are applied per user account. This means all requests made with the same API key count toward the same rate limit, regardless of the IP address they originate from.

Example: If you make 50 requests from your office and 20 requests from your home, all 70 requests count toward your 60/minute limit.

Unauthenticated Requests

Unauthenticated requests (those without a valid API key) are rate limited per IP address.

Rate Limit Headers

Every API response includes headers that help you track your rate limit status:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed per minute
X-RateLimit-Remaining	The number of requests remaining in the current minute window
X-RateLimit-Limit-Second	The maximum number of requests allowed per second
X-RateLimit-Remaining-Second	The number of requests remaining in the current second window
X-RateLimit-Reset	Number of seconds until the enforcing window resets
X-RateLimit-Limited-By	Which window enforced the limit: minute or second

Example Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Limit-Second: 2
X-RateLimit-Remaining-Second: 1
X-RateLimit-Reset: 2015967110
X-RateLimit-Limited-By: minute

The X-RateLimit-Limited-By header tells you which rate limit window is currently restricting your requests, helping you understand whether you need to slow down your request rate (second) or wait for the minute window to reset.

Rate Limit Exceeded Response

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "message": "You have exceeded your user rate limit.",
  "status_code": 429,
  "retry_after": 42
}

The retry_after field indicates how many seconds you should wait before making another request.

Best Practices

1. Monitor Rate Limit Headers

Always check the X-RateLimit-Remaining header to know how many requests you have left:

$response = $client->get('https://api.lindris.com/v1/people', [
    'headers' => [
        'Authorization' => 'Bearer ' . $apiKey,
    ],
]);

$remaining = $response->getHeader('X-RateLimit-Remaining')[0];

if ($remaining < 10) {
    // Slow down or wait before making more requests
    sleep(5);
}

2. Implement Exponential Backoff

When you receive a 429 response, wait before retrying. Implement exponential backoff for better results:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        const response = await fetch(url, options);

        if (response.status !== 429) {
            return response;
        }

        // Exponential backoff: wait 2^attempt seconds
        const waitTime = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitTime));
    }

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

3. Batch Your Requests

Instead of making many small requests, batch your operations when possible. For example, when syncing thousands of contacts, group them into batches and add delays between batches:

$contacts = [...]; // Your contacts array
$batchSize = 50;
$batches = array_chunk($contacts, $batchSize);

foreach ($batches as $batch) {
    // Process batch
    foreach ($batch as $contact) {
        $client->post('https://api.lindris.com/v1/people', [
            'json' => $contact,
            'headers' => ['Authorization' => 'Bearer ' . $apiKey],
        ]);
    }

    // Wait 60 seconds after each batch to stay within limits
    sleep(60);
}

4. Respect the retry_after Value

When you receive a 429 response, use the retry_after value to determine when to retry:

const response = await fetch(url, options);

if (response.status === 429) {
    const data = await response.json();
    const retryAfter = data.retry_after;

    console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));

    // Retry the request
    return fetch(url, options);
}

5. Distribute Load Over Time

For large sync operations, spread your requests over a longer period:

// Instead of syncing 3,600 contacts in 1 minute (60 req/min)
// Sync them over 30 minutes (2 req/sec = 60 req/min sustained)

foreach ($contacts as $contact) {
    $client->post('https://api.lindris.com/v1/people', [
        'json' => $contact,
        'headers' => ['Authorization' => 'Bearer ' . $apiKey],
    ]);

    // Wait 500ms between requests (2 requests per second)
    usleep(500000);
}

Common Questions

Can I request higher rate limits?

Yes! If you have a legitimate use case that requires higher rate limits (such as a large one-time data sync), please contact our support team. We can temporarily or permanently increase your limits.

Do rate limits reset immediately after 1 minute?

Rate limits use sliding windows:

• Per-minute limit: Resets 60 seconds after your first request in the current window
• Per-second limit: Resets 1 second after each request

Check the X-RateLimit-Reset header to see how many seconds until the limiting window resets. The X-RateLimit-Limited-By header tells you which window is enforcing the limit.

What happens if I consistently hit rate limits?

Consistently hitting rate limits may trigger additional security measures. If you regularly need to exceed the default limits, please contact us to discuss increasing your limits rather than repeatedly hitting the 429 threshold.

Are there different limits for different endpoints?

Most API endpoints use the default dual rate limits (60 requests per minute + 2 requests per second sustained). However, some specific endpoints may have custom rate limits tailored to their resource requirements.

Check the rate limit headers in each API response to see the limits in effect for that endpoint. All endpoints enforce both per-minute and per-second limits to balance burst traffic allowance with sustained load control.

Getting Help

If you have questions about rate limits or need assistance implementing rate limit handling in your integration, please contact our support team or consult the Error Handling documentation.