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

# Rate Limiting

> Understanding API rate limits

# Rate Limiting

SwiftPay implements rate limiting to ensure fair usage and protect our infrastructure. Rate limits are applied per API key.

## Rate Limits

| Tier       | Requests per Minute | Requests per Hour |
| ---------- | ------------------: | ----------------: |
| Standard   |                 100 |             1,000 |
| Premium    |                 500 |             5,000 |
| Enterprise |              Custom |            Custom |

<Note>
  Your rate limit tier is based on your account plan. Contact support to
  upgrade.
</Note>

## Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix timestamp when the rate limit resets      |

```bash theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```

## Rate Limit Exceeded

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

```json theme={null}
{
   "success": false,
   "error": {
      "type": "rate_limit_exceeded",
      "message": "Rate limit exceeded. Please retry after 45 seconds.",
      "requestId": "req_abc123",
      "retryAfter": 45
   }
}
```

The `Retry-After` header indicates how many seconds to wait before retrying.

## Handling Rate Limits

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function apiRequest(url, options, retries = 3) {
    for (let i = 0; i < retries; i++) {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || 60;
        console.log(`Rate limited. Retrying after ${retryAfter}s...`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      return response;
    }
    
    throw new Error('Max retries exceeded');
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def api_request(url, **kwargs):
      max_retries = 3

      for attempt in range(max_retries):
          response = requests.request(url=url, **kwargs)

          if response.status_code == 429:
              retry_after = int(response.headers.get('Retry-After', 60))
              print(f"Rate limited. Retrying after {retry_after}s...")
              time.sleep(retry_after)
              continue

          return response

      raise Exception('Max retries exceeded')
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Implement Exponential Backoff" icon="clock">
    When retrying after rate limits, use exponential backoff to gradually
    increase wait times: `javascript const delay = Math.min(1000 *
              Math.pow(2, attempt), 30000); `
  </Accordion>

  {" "}

  <Accordion title="Cache Responses" icon="database">
    Cache API responses where appropriate to reduce the number of requests: -
    Balance information (cache for 30-60 seconds) - Session details (cache until
    status changes) - Webhook endpoint lists (cache for several minutes)
  </Accordion>

  {" "}

  <Accordion title="Batch Operations" icon="layer-group">
    Where possible, batch multiple operations into a single request to reduce API
    calls.
  </Accordion>

  <Accordion title="Monitor Usage" icon="chart-line">
    Monitor your API usage in the dashboard to understand your patterns and
    avoid hitting limits.
  </Accordion>
</AccordionGroup>

## Rate Limit Exceptions

Certain endpoints have different rate limits:

| Endpoint                     | Limit                     |
| ---------------------------- | ------------------------- |
| `POST /api/checkout/:id/pay` | 10 per minute per session |
| `GET /api/balance`           | 30 per minute             |

## Need Higher Limits?

If you need higher rate limits, contact our sales team to discuss Enterprise pricing:

<Card title="Contact Sales" icon="envelope" href="mailto:sales@swiftpay.cx">
  Get custom rate limits for your business needs
</Card>