Rate Limits

Understanding and working within API rate limits.

General API Rate Limits

All API endpoints are protected by rate limiting. The default limits apply to all authenticated requests:

QR Code Rate Limits (Tier-Based)

QR code generation has tier-specific rate limits based on your workspace plan:

Password-Protected Links

Password verification endpoints have stricter limits to protect against brute-force attacks:

Rate Limit Headers

Every API response includes rate limit information in the headers:

Handling Rate Limits

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

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
Retry-After: 45

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retryAfter": 45,
      "limit": 100,
      "windowMs": 900000
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Best Practices

1. Monitor rate limit headers - Check X-RateLimit-Remainingproactively to avoid hitting limits.
2. Implement exponential backoff - When rate limited, wait and retry with increasing delays.
3. Batch requests when possible - Use bulk endpoints to reduce the number of API calls.
4. Cache responses - Cache read-only data locally to reduce API calls.
5. Spread requests over time - Avoid bursts by distributing requests evenly.

Monitoring Example

async function apiRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'X-API-Key': apiKey,
      ...options.headers,
    },
  });

  // Log rate limit info
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const limit = response.headers.get('X-RateLimit-Limit');
  const reset = response.headers.get('X-RateLimit-Reset');

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

  // Warn when getting low
  if (remaining && parseInt(remaining) < 10) {
    console.warn('Rate limit getting low!');
  }

  // Handle rate limit exceeded
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    const waitTime = retryAfter ? parseInt(retryAfter) : 60;

    console.log(`Rate limited. Waiting ${waitTime}s...`);
    await new Promise(r => setTimeout(r, waitTime * 1000));

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

  return response;
}

Distributed Rate Limiting

The API uses Redis-based distributed rate limiting for multi-instance deployments. This ensures consistent rate limiting across all API servers. If Redis is unavailable, the API falls back to in-memory rate limiting per server.