Rate Limits

SplitRoute API implements rate limiting to ensure fair usage and system stability. This document explains the rate limits for different API key tiers and how to handle rate limit errors.

Rate Limit by Tier

Rate limits vary based on your API key tier:

Rate Limit Headers

When you make a request to the SplitRoute API, the response includes headers that provide information about your current rate limit status:

HTTP
1
X-RateLimit-Limit: 60
2
X-RateLimit-Remaining: 58
3
X-RateLimit-Reset: 1609459200

• X-RateLimit-Limit: The maximum number of requests you can make per hour
• X-RateLimit-Remaining: The number of requests remaining in the current rate limit window
• X-RateLimit-Reset: The time at which the current rate limit window resets (Unix timestamp)

Rate Limit Errors

If you exceed your rate limit, the API will return a 429 Too Many Requests response with the following body:

JSON
1
{
2
  "error":  "rate_limit_exceeded",
3
  "message":  "Rate limit exceeded. Please try again later.",
4
  "retry_after":  120
5
}

The retry_after field indicates the number of seconds you should wait before making another request.

Best Practices

To avoid hitting rate limits, follow these best practices:

1. Implement exponential backoff: When you receive a rate limit error, wait for the specified retry_after period before retrying, and increase the wait time exponentially for consecutive failures.

2. Cache responses: Cache responses that don't change frequently to reduce the number of API calls.

3. Use webhooks: Instead of polling for invoice status changes, use webhooks to receive notifications when events occur.

4. Monitor your usage: Keep track of your API usage and adjust your implementation if you're approaching your limits.

5. Upgrade your tier: If you consistently hit rate limits, consider upgrading to a higher API key tier.

Example: Handling Rate Limits

Here's an example of how to handle rate limits in your code:

JAVASCRIPT
1
async function makeApiRequest(url, options) {
2
  let retries = 0;
3
  const maxRetries = 5;
4
  let retryAfter = 1;
5
6
  while (retries < maxRetries) {
7
    try {
8
      const response = await fetch(url, options);
9
      
10
      if (response.status === 429) {
11
        const data = await response.json();
12
        retryAfter = data.retry_after || Math.pow(2, retries);
13
        console.log(`Rate limit exceeded. Retrying in ${retryAfter} seconds.`);
14
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
15
        retries++;
16
      } else {
17
        return response;
18
      }
19
    } catch (error) {
20
      console.error('API request failed:', error);
21
      throw error;
22
    }
23
  }
24
  
25
  throw new Error('Maximum retries exceeded');
26
}

Free Tier Limitations

In addition to the rate limits above, users without an API key (No AUTH tier) have the following limitations:

1. Limited to 1000 requests per hour shared among all unauthenticated users
2. No limit for invoices
3. Highest service fee at 0.5%
4. No access to the Dashboard

Register for a FREE tier API key to get your individual rate limit allocation, access to the Dashboard, and other features. Upgrade to a paid tier (BASIC, PRO, or ENTERPRISE) to reduce service fees and get higher rate limits.