Skip to main content

​
Why Rate Limits Exist

Revolv3 enforces rate limits (also called “throttling”) on API requests to:
  • Maintain performance: Ensure the API stays fast for everyone
  • Prevent abuse: Stop malicious or poorly-designed integrations from overwhelming the system
  • Ensure fairness: Give all merchants equal access to resources
  • Protect infrastructure: Keep the system stable under high load
Think of it like speed limits on a highway—they keep traffic flowing smoothly for everyone.

​
Rate Limits for One-Time Payments

For one-time payment transactions, Revolv3 enforces the following rate limits:

​
Per IP Address Limits

  • 20 requests per second per IP address
  • 20,000 requests within a rolling 15-minute window
What this means:
  • You can make up to 20 API calls per second from the same IP address
  • You can make up to 20,000 API calls in any 15-minute period
  • Limits are tracked per IP address (so different servers have separate limits)

​
How Throttling Works

  • IP-based: Limits are applied per IP address making the requests
  • Automatic: Revolv3 automatically enforces limits—no configuration needed
  • Rolling window: The 15-minute limit uses a rolling window (not fixed 15-minute blocks)

​
What Happens When You Exceed the Limit?

If you exceed the rate limits, Revolv3 will return a 429 Too Many Requests HTTP status code.

​
429 Response

Status Code: 429 Too Many Requests What it means:
  • You’ve made too many requests too quickly
  • You need to slow down and wait before making more requests
  • The limit will reset after a short period
What to do:
  1. Stop making requests immediately
  2. Wait a few seconds (or minutes if you hit the 15-minute limit)
  3. Retry with exponential backoff (wait longer between retries)
  4. Implement rate limiting in your code to prevent hitting limits

​
Example 429 Response

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after a few seconds.",
  "retryAfter": 5
}

​
Best Practices for Handling Rate Limits

​
1. Implement Exponential Backoff

When you get a 429 error, wait before retrying, and increase the wait time for each retry: 
// Pseudo-code example
let retryDelay = 1; // Start with 1 second
const maxRetries = 5;

for (let i = 0; i < maxRetries; i++) {
  try {
    const response = await makeApiRequest();
    return response;
  } catch (error) {
    if (error.status === 429 && i < maxRetries - 1) {
      await sleep(retryDelay);
      retryDelay *= 2; // Double the delay each time
    } else {
      throw error;
    }
  }
}

​
2. Queue Requests

Instead of making requests immediately, queue them and process at a controlled rate:
  • Use a message queue (RabbitMQ, AWS SQS, etc.)
  • Process requests at a rate below the limit (e.g., 15 requests/second to stay safe)
  • Batch requests when possible

​
3. Monitor Your Usage

Track how many requests you’re making:
  • Log request counts
  • Monitor for 429 errors
  • Set up alerts if you’re approaching limits
  • Review your code for unnecessary API calls

​
4. Optimize Your Integration

Reduce the number of API calls you need:
  • Batch operations: Process multiple items in one request when possible
  • Cache responses: Store data you’ve already fetched
  • Use webhooks: Instead of polling, listen for events
  • Combine requests: Get multiple pieces of data in one call when the API supports it

​
Rate Limits for Other Operations

Subscriptions and recurring payments may have different rate limits. Check with Revolv3 support or your account manager for specific limits for your use case. Webhooks (incoming from Revolv3) are not subject to these rate limits—you can receive as many webhooks as Revolv3 sends.

​
Calculating Your Needs

Example calculation:
  • 20 requests/second = 1,200 requests/minute = 72,000 requests/hour
  • 20,000 requests per 15 minutes = ~1,333 requests/minute
For most businesses:
  • These limits are more than sufficient
  • You’d need very high transaction volume to hit them
  • If you’re hitting limits, you may need to optimize your integration
If you need higher limits:
  • Contact Revolv3 support
  • Explain your use case and volume
  • They may be able to adjust limits for your account

​
Common Scenarios

​
Scenario 1: High-Volume Checkout

Problem: Processing many checkout requests simultaneously Solution:
  • Queue requests and process at a controlled rate
  • Use webhooks instead of polling for status updates
  • Batch operations when possible

​
Scenario 2: Bulk Operations

Problem: Need to process many payments at once (e.g., payroll, bulk refunds) Solution:
  • Spread operations over time
  • Process in batches with delays between batches
  • Contact Revolv3 if you need to process very large batches

​
Scenario 3: Retry Logic Causing Issues

Problem: Aggressive retry logic hitting rate limits Solution:
  • Implement exponential backoff
  • Respect 429 responses (don’t retry immediately)
  • Add jitter (random delay) to prevent thundering herd

​
Monitoring and Alerts

Set up monitoring to track:
  • Request rate: How many requests per second you’re making
  • 429 errors: When you hit rate limits
  • Response times: Slow responses might indicate you’re approaching limits
  • Error rates: High error rates might indicate throttling issues

​
Troubleshooting

​
If You’re Getting 429 Errors Frequently

  1. Check your request rate: Count how many requests you’re making per second
  2. Review your code: Look for unnecessary API calls or tight loops
  3. Implement rate limiting: Add client-side rate limiting to stay under limits
  4. Contact support: If you legitimately need higher limits, Revolv3 may be able to help

​
If You Need Higher Limits

Contact Revolv3 support with:
  • Your use case and why you need higher limits
  • Your expected request volume
  • Your account information
They can evaluate your needs and potentially adjust limits.

​
Summary

  • Rate limits: 20 requests/second, 20,000 per 15 minutes (per IP)
  • 429 errors: You’ve exceeded the limit—slow down and retry
  • Best practice: Implement exponential backoff and rate limiting in your code
  • Optimization: Reduce API calls through batching, caching, and webhooks
  • Need more?: Contact Revolv3 support if you need higher limits

​
Next Steps