API Rate Limits

The SocialRails API enforces rate limits to maintain fair usage and platform stability. Limits are applied per user account on an hourly window, all API keys under the same account share one limit.

Limits by Plan

Free and Trial plans do not have API access.

Rate Limit Headers

Every API response includes these headers:

Example headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1709402400

Handling 429 Responses

When you exceed your rate limit, you'll receive a 429 status code:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Limit: 300 requests per hour."
  }
}

Recommended Retry Strategy

1. Read the X-RateLimit-Reset header to know when the window resets
2. Wait until that time before retrying
3. Implement exponential backoff for consecutive 429s
4. Consider caching responses that don't change frequently

Example: JavaScript Retry Logic

async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
 
    if (response.status === 429) {
      const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
      const waitMs = (resetTime * 1000) - Date.now() + 1000;
      await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 1000)));
      continue;
    }
 
    return response;
  }
  throw new Error('Rate limit exceeded after retries');
}

Tips for Staying Under Limits

• Cache responses, Store data locally and only re-fetch when needed
• Use pagination wisely, Fetch larger pages (up to 100) instead of many small requests
• Batch operations, Group related actions instead of making them one at a time
• Monitor usage, Check X-RateLimit-Remaining to track your consumption
• Upgrade if needed, Higher plans offer significantly more capacity