← Back to Home

API Documentation

Rate Limiting

Understand rate limits and how to handle them in your applications.

Overview

All Social Unlocks API endpoints are rate limited to prevent abuse and ensure fair usage for all developers. Rate limits are applied per IP address and reset every minute.

Rate Limit Limits

EndpointRate LimitWindowScope
Key Validation API100 requests1 minutePer IP address
Lockers API60 requests1 minutePer IP address

Rate Limit Headers

Rate limit information is included in every API response header:

Response Headers

X-RateLimit-Limit- Maximum requests allowed per window
X-RateLimit-Remaining- Remaining requests in current window
X-RateLimit-Reset- Unix timestamp when the rate limit resets

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 status code with additional information:

429 Too Many Requests
{
  "error": "Too many requests. Please try again later."
}

The response will include the standard rate limit headers showing when you can try again.

Best Practices

Implement Proper Handling
  • • Monitor rate limit headers in responses
  • • Implement exponential backoff
  • • Cache responses when appropriate
  • • Use request queuing for high-volume apps
Avoid Common Mistakes
  • • Don't ignore 429 responses
  • • Don't make requests too frequently
  • • Don't retry immediately after 429
  • • Don't hardcode retry delays

Implementation Examples

JavaScript with Exponential Backoff
async function makeRequest(url, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url);
      
      if (response.status === 429) {
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Monitoring Usage

Keep track of your API usage to avoid hitting rate limits:

Check Headers

Always check the X-RateLimit-Remaining header to see how many requests you have left in the current window.

Plan Ahead

If you know you'll need to make many requests, spread them out over time or implement caching to reduce API calls.