> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Production Environment Limitations

> Understand API rate limits and throttling for production. Learn the limits, what happens when you exceed them, and how to handle rate limit errors.

## 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

```json theme={null}
{
  "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:

```javascript theme={null}
// 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

* **[Error Responses](/docs/error-codes/error-responses)** — Learn how to handle all API errors
* **[Production vs Sandbox](/docs/getting-started/production-vs-sandbox)** — Understand environment differences
* **[Webhooks](/docs/webhook-events/webhook)** — Use webhooks to reduce polling and API calls

***