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

# Rate Limits

> Understanding API rate limits and best practices

## Overview

Transaction API implements rate limiting to ensure fair usage and system stability. Different endpoints have different rate limits based on their resource requirements.

## Rate Limit Tiers

<Columns cols={3}>
  <Card title="Authentication" icon="key">
    **5 requests/minute**

    * `/auth/register`
    * `/auth/login`
    * `/auth/verify-email`
    * `/auth/resend-verification`
  </Card>

  <Card title="Payment Creation" icon="credit-card">
    **10 requests/minute**

    * `/payment/create`
    * `/payment/select-crypto`
  </Card>

  <Card title="Other Endpoints" icon="server">
    **100 requests/minute**

    * All other API endpoints
  </Card>
</Columns>

## Rate Limit Headers

All API responses include rate limit information in the headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

<ParamField path="X-RateLimit-Limit" type="integer">
  Maximum requests allowed per window
</ParamField>

<ParamField path="X-RateLimit-Remaining" type="integer">
  Number of requests remaining in current window
</ParamField>

<ParamField path="X-RateLimit-Reset" type="integer">
  Unix timestamp when the rate limit resets
</ParamField>

## Rate Limit Exceeded

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "success": false,
  "error": {
    "status": 429,
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  },
  "data": null
}
```

## Best Practices

### Implement Exponential Backoff

```javascript theme={null}
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        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 Usage

```javascript theme={null}
function checkRateLimit(response) {
  const limit = parseInt(response.headers.get('X-RateLimit-Limit'));
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
  const reset = parseInt(response.headers.get('X-RateLimit-Reset'));
  
  console.log(`Rate limit: ${remaining}/${limit} remaining`);
  console.log(`Resets at: ${new Date(reset * 1000)}`);
  
  if (remaining < 10) {
    console.warn('Rate limit nearly exceeded!');
  }
}
```

### Batch Operations

Instead of making multiple individual requests, batch operations when possible:

```javascript theme={null}
// ❌ Don't do this
for (const customer of customers) {
  await createCustomer(customer);
}

// ✅ Do this instead
const batchPromises = customers.map(customer => createCustomer(customer));
await Promise.all(batchPromises);
```

## Rate Limit Strategies

### For High-Volume Applications

<Steps>
  <Step title="Implement Caching">
    Cache frequently accessed data to reduce API calls.
  </Step>

  <Step title="Use Webhooks">
    Subscribe to webhook events instead of polling for updates.
  </Step>

  <Step title="Batch Requests">
    Combine multiple operations into single requests when possible.
  </Step>

  <Step title="Queue Operations">
    Use a queue system to manage request timing and avoid bursts.
  </Step>
</Steps>

### For Development

<Steps>
  <Step title="Use Sandbox Mode">
    Test with sandbox mode which has higher rate limits.
  </Step>

  <Step title="Implement Delays">
    Add delays between requests during development.
  </Step>

  <Step title="Monitor Headers">
    Always check rate limit headers in your responses.
  </Step>
</Steps>

## Monitoring and Alerts

### Set Up Monitoring

```javascript theme={null}
// Example monitoring setup
class RateLimitMonitor {
  constructor() {
    this.usage = new Map();
  }
  
  trackRequest(endpoint, headers) {
    const limit = parseInt(headers.get('X-RateLimit-Limit'));
    const remaining = parseInt(headers.get('X-RateLimit-Remaining'));
    const reset = parseInt(headers.get('X-RateLimit-Reset'));
    
    this.usage.set(endpoint, {
      limit,
      remaining,
      reset,
      lastChecked: Date.now()
    });
  }
  
  getUsage(endpoint) {
    return this.usage.get(endpoint);
  }
  
  isNearLimit(endpoint, threshold = 0.8) {
    const usage = this.getUsage(endpoint);
    if (!usage) return false;
    
    return usage.remaining / usage.limit < (1 - threshold);
  }
}
```

### Alert Configuration

Set up alerts when approaching rate limits:

```javascript theme={null}
if (rateLimitMonitor.isNearLimit('payment/create', 0.9)) {
  console.warn('Payment creation rate limit at 90%');
  // Send alert to monitoring system
}
```

## Common Scenarios

<AccordionGroup>
  <Accordion title="E-commerce Checkout">
    **Scenario:** High-volume payment processing

    **Solution:**

    * Use webhooks instead of polling payment status
    * Implement request queuing
    * Cache product and price data
  </Accordion>

  <Accordion title="Mobile App Integration">
    **Scenario:** Frequent API calls from mobile devices

    **Solution:**

    * Implement local caching
    * Batch multiple operations
    * Use background sync
  </Accordion>

  <Accordion title="Analytics Dashboard">
    **Scenario:** Real-time data fetching for dashboards

    **Solution:**

    * Use WebSocket connections
    * Implement data aggregation
    * Cache dashboard data
  </Accordion>
</AccordionGroup>

## Rate Limit Increases

For applications requiring higher rate limits:

1. **Contact Support:** Reach out to our support team with your use case
2. **Provide Metrics:** Share your current usage patterns and requirements
3. **Business Justification:** Explain why higher limits are needed
4. **Implementation Plan:** Show how you'll handle the increased volume

<Note>
  **Enterprise Plans:** Higher rate limits are available for enterprise customers. Contact sales for more information.
</Note>