Rate Limiting

Overview

Rate limiting is used to control the number of API requests a merchant can make within a specific period. This ensures system stability, prevents abuse, and maintains high performance across the PayOS platform. It is essential for merchants to monitor their API usage and implement strategies to manage rate limits effectively.

How Rate Limiting Works

• Rate Limit Threshold:

  • PayOS sets a maximum number of requests per minute for each API key.
  • Exceeding the threshold will result in 429 Too Many Requests responses.

• Rate Limit Scope:

  • Rate limits are applied per API key.
  • Limits may vary between sandbox and production environments to allow more flexibility during development.

Example Rate Limit Error Response

If your API key exceeds the rate limit, you will receive a response like the following:

1
{
2
  "error": {
3
    "code": "429",
4
    "message": "Too Many Requests",
5
    "details": "You have exceeded the allowed rate limit. Please wait before making further requests."
6
  },
7
  "retry_after": 60
8
}

Handling Rate Limits in Your Integration

1. Monitor API Usage:

   • Use the PayOS dashboard to track your API request volume in real-time.

2. Implement Exponential Backoff:

   • Use exponential backoff when retrying requests to avoid further rate limit violations.

3. Handle 429 Responses Gracefully:

   • If you encounter a 429 Too Many Requests response, use the Retry-After header to determine when it is safe to retry the request.

Example of Exponential Backoff in JavaScript

1
function makeApiCallWithBackoff(url, attempt = 1) {
2
    fetch(url)
3
        .then(response => {
4
            if (response.status === 429) {
5
                const retryAfter = response.headers.get('Retry-After') || 1;
6
                const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
7
                console.log(`Rate limit hit. Retrying in ${waitTime / 1000} seconds...`);
8
                setTimeout(() => makeApiCallWithBackoff(url, attempt + 1), waitTime);
9
            } else {
10
                return response.json();
11
            }
12
        })
13
        .then(data => console.log(data))
14
        .catch(err => console.error('API call failed:', err));
15
}

Monitoring API Limits via Webhooks

PayOS can also notify merchants via webhooks if their API usage approaches predefined thresholds. Example webhook payload:

1
{
2
  "event": "rate_limit.warning",
3
  "data": {
4
    "api_key": "abc123",
5
    "usage": 950,
6
    "limit": 1000,
7
    "reset_time": "2024-10-18T00:00:00Z"
8
  }
9
}

Best Practices for Managing Rate Limits

• Batch Requests:

  • Where possible, batch multiple API calls into a single request to minimize usage.

• Use Caching:

  • Cache responses from the PayOS API to avoid redundant requests.

• Monitor Usage Trends:

  • Regularly review your API usage patterns and adjust your implementation to stay within limits.

Conclusion

Rate limiting ensures that PayOS remains stable and responsive for all merchants. By following best practices, merchants can efficiently manage their API usage, avoid disruptions, and maintain smooth operations across their payment systems.