High-Traffic Best Practices

Monitoring Only

Rate limits are currently in a monitoring-only phase and are not being enforced. No requests will be blocked at this time. We will provide advance notice before enforcement begins.

When running push notification campaigns, email blasts, or other marketing activities that drive sudden traffic spikes to your website or app, proper preparation ensures your consent management continues to work smoothly.

Understanding the Problem

When you send a push notification to your users, many will click through to your website or open your app within a short time window. This creates a traffic spike.

Why this matters for consent:

• Returning users are served from cache - no problem
• New users require a fresh request to our servers to fetch their consent preferences

If many new users arrive simultaneously, all their first-hit requests go directly to our servers at once. This is the most common cause of rate limit issues.

For details on the actual rate limits, see the Rate Limits documentation.

Preparing for High-Traffic Events

1. Pre-warm your cache

Before launching a campaign, make requests to the banner API endpoint to warm the cache.

Important: The cache is keyed by domain ID, language, and location - so you need to warm the cache for each language/location combination your users will request.

# Cache warm-up request structure
curl -I "https://app.secureprivacy.ai/api/banner/v2/template/YOUR_DOMAIN_ID?Language=en&Location=US"

# Warm cache for multiple locations your users may come from
curl -I "https://app.secureprivacy.ai/api/banner/v2/template/YOUR_DOMAIN_ID?Language=en&Location=GB"
curl -I "https://app.secureprivacy.ai/api/banner/v2/template/YOUR_DOMAIN_ID?Language=de&Location=DE"

2. Stagger your notifications

Instead of sending all notifications at once, batch them over 5-10 minutes:

Total Users	Recommended Batch Size	Interval
10,000	1,000 users	Every 30 seconds
50,000	2,500 users	Every 30 seconds
100,000+	5,000 users	Every 30 seconds

3. Schedule during off-peak hours

If possible, schedule campaigns during periods when your regular traffic is lower. This provides more headroom for the spike.

4. Monitor your dashboard

Keep an eye on the Secure Privacy API responses during your campaign for any rate limit warnings or errors.

Campaign Launch Checklist

Before launching any high-traffic campaign:

• Domain/app configured: Ensure your domain or app is fully configured in Secure Privacy
• Cache warmed: Make requests for each language/location combination you expect
• Batch strategy: Plan to stagger notifications if sending to large audiences
• Monitoring ready: Have your API monitoring dashboard open during the campaign
• Support contacted (if needed): Reach out to [email protected] for rate limit increases if expecting very high traffic

Handling Rate Limits in Code

Implement Exponential Backoff

If you’re calling our API directly, implement retry logic with exponential backoff:

JavaScript

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

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 1;
      const delay = retryAfter * 1000 * Math.pow(2, attempt);
      const jitter = Math.random() * 1000;

      await new Promise(resolve => setTimeout(resolve, delay + jitter));
      continue;
    }

    return response;

}

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

Python

import time
import random
import requests

def fetch_with_retry(url, headers=None, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 1))
            delay = retry_after * (2 ** attempt)
            jitter = random.random()

            time.sleep(delay + jitter)
            continue

        return response

    raise Exception('Max retries exceeded')

Monitor Rate Limit Headers

Proactively slow down requests before hitting limits by checking the X-RateLimit-Remaining header:

JavaScript

async function makeRequest(url) {
  const response = await fetch(url);

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

if (remaining < 10) {
console.warn("Approaching rate limit, slowing down...");
await new Promise(resolve => setTimeout(resolve, 1000));
}

return response;
}

Cache Responses Locally

Reduce API calls by caching consent data locally:

JavaScript

// Store consent data in localStorage after first fetch
const CACHE_KEY = 'sp_consent_cache';
const CACHE_DURATION = 3600000; // 1 hour

function getCachedConsent() {
  const cached = localStorage.getItem(CACHE_KEY);
  if (!cached) return null;

  const { data, timestamp } = JSON.parse(cached);
  if (Date.now() - timestamp > CACHE_DURATION) {
    localStorage.removeItem(CACHE_KEY);
    return null;
  }

  return data;
}

function setCachedConsent(data) {
  localStorage.setItem(CACHE_KEY, JSON.stringify({
    data,
    timestamp: Date.now()
  }));
}

What Happens When Limits Are Exceeded

If your domain or app exceeds rate limits, our API returns a 429 Too Many Requests response. Our SDKs handle this gracefully:

• For cached requests: Users will still see your banner (served from cache)
• For uncached requests: The banner may be delayed briefly while the rate limit resets

The Retry-After header indicates how long to wait before retrying.

Getting Help

If you’re planning a large campaign and need assistance:

1. Contact support: [email protected]
2. Provide details: Expected traffic volume, timing, and domain(s) or app(s) involved
3. Plan ahead: Reach out at least 48 hours before major campaigns

Our team can help you prepare and, if necessary, temporarily increase your rate limits for the event.