Magnetite
Docs

Rate Limits

Implemented

Understanding and working with Magnetite API rate limits to ensure optimal performance.

Current Rate Limits

POST
Add Lead Endpoint
/api/campaigns/:id/leads
Limit:10 requests/minute
Burst:5 requests
Window:Rolling 60 seconds
GET
Read Endpoints
Other read operations
Limit:60 requests/minute
Burst:20 requests
Window:Rolling 60 seconds

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1703123456
X-RateLimit-Window: 60

X-RateLimit-Limit

The maximum number of requests allowed in the current window

X-RateLimit-Remaining

The number of requests remaining in the current window

X-RateLimit-Reset

Unix timestamp when the rate limit window resets

X-RateLimit-Window

Duration of the rate limit window in seconds

Rate Limit Exceeded Response

When you exceed the rate limit, the API will return a 429 Too Many Requests response:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703123456
X-RateLimit-Window: 60

{
  "error": "Rate limit exceeded. Maximum 10 requests per 60 seconds allowed.",
  "retryAfter": 45
}

Best Practices

Implement Exponential Backoff

When you receive a 429 response, wait before retrying. Use exponential backoff to gradually increase wait times:

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

      if (response.status === 429) {
        const retryAfter = response.headers.get('X-RateLimit-Reset');
        const waitTime = retryAfter ?
          Math.max(0, parseInt(retryAfter) * 1000 - Date.now()) :
          Math.pow(2, attempt) * 1000; // Exponential backoff

        console.log(`Rate limited, waiting ${waitTime}ms before retry`);
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}
Monitor Rate Limit Headers

Always check the rate limit headers in responses to proactively manage your request rate:

function checkRateLimit(response) {
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const reset = parseInt(response.headers.get('X-RateLimit-Reset'));

  if (remaining < 3) {
    const waitTime = Math.max(0, reset * 1000 - Date.now());
    console.log(`Approaching rate limit. ${remaining} requests remaining.`);
    console.log(`Consider waiting ${waitTime}ms before next request.`);
  }

  return {
    remaining,
    reset: new Date(reset * 1000),
    shouldWait: remaining < 3
  };
}
Batch Processing with Delays

For bulk lead imports, implement proper delays between requests:

async function importLeadsWithRateLimit(leads, campaignId, apiKey) {
  const results = [];

  for (let i = 0; i < leads.length; i++) {
    const lead = leads[i];

    try {
      const response = await fetch(
        `https://magnetite.ai/api/campaigns/${campaignId}/leads`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify(lead)
        }
      );

      const result = await response.json();
      results.push({ lead, success: response.ok, result });

      console.log(`Added lead ${i + 1}/${leads.length}: ${lead.email}`);

    } catch (error) {
      results.push({ lead, success: false, error: error.message });
    }

    // Wait 1 second between requests to stay under rate limits
    if (i < leads.length - 1) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }

  return results;
}

Enterprise Rate Limits

Custom Rate Limits Available
Enterprise plans include options for increased rate limits and burst capacity
  • • Custom limits up to 100 requests/minute
  • • Dedicated API endpoints for high-volume usage
  • • Priority processing for lead submissions
  • • Custom burst allowances for peak usage periods
  • • Dedicated support for rate limit optimization

Need Help?

Having issues with rate limits or need to discuss your usage patterns?

Error Handling Guide →Add Lead API →