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

# Rate Limits

> Understanding API rate limits and quotas

# Rate Limits

PriveTag B2A API implements rate limiting to ensure fair usage and system stability.

## Rate Limit Tiers

| Plan           | Requests/Minute | Daily Quota | Concurrent Requests |
| -------------- | --------------- | ----------- | ------------------- |
| **Free**       | 10              | 100         | 2                   |
| **Basic**      | 60              | 1,000       | 5                   |
| **Premium**    | 300             | 10,000      | 20                  |
| **Enterprise** | Unlimited       | Unlimited   | Unlimited           |

<Info>
  Rate limits are applied per API key. If you need higher limits, [contact us](mailto:support@privetag.com) to discuss Enterprise plans.
</Info>

## Rate Limit Headers

Every API response includes rate limit information in headers:

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

### Example Response Headers

```
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1702209600
X-Daily-Quota-Limit: 1000
X-Daily-Quota-Remaining: 856
Content-Type: application/json
```

## Rate Limit Exceeded

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

```json theme={null}
{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "details": "Maximum 60 requests per minute. Please wait 15 seconds.",
  "retry_after": 15
}
```

### Response Headers on 429

```
HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1702209615
```

## Quota Exceeded

When daily quota is exhausted:

```json theme={null}
{
  "success": false,
  "error": "Daily quota exceeded",
  "code": "QUOTA_EXCEEDED",
  "details": "Daily limit of 1000 requests reached. Resets at midnight UTC.",
  "quota_reset": "2025-12-11T00:00:00Z"
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Implement exponential backoff">
    When receiving 429 errors, use exponential backoff:

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

    def make_request_with_backoff(url, headers, data, max_retries=3):
        for attempt in range(max_retries):
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
                time.sleep(retry_after)
                continue

            return response

        raise Exception("Max retries exceeded")
    ```
  </Accordion>

  <Accordion title="Monitor rate limit headers">
    Check headers proactively to avoid hitting limits:

    ```javascript theme={null}
    const response = await fetch(url, { headers });
    const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));

    if (remaining < 10) {
      console.warn('Rate limit running low:', remaining);
      // Implement throttling logic
    }
    ```
  </Accordion>

  <Accordion title="Cache recommendations">
    Cache `/recommend` responses for similar contexts to reduce API calls:

    ```python theme={null}
    from functools import lru_cache
    import hashlib

    def get_cache_key(user_profile, location):
        data = f"{user_profile['travel_type']}-{location['city']}"
        return hashlib.md5(data.encode()).hexdigest()

    @lru_cache(maxsize=100)
    def get_cached_recommendations(cache_key):
        # Fetch from API
        pass
    ```
  </Accordion>

  <Accordion title="Use batch operations">
    Instead of multiple single requests, use appropriate batch sizes:

    * `/recommend`: Request up to 20 items per call
    * `/inventory`: Use filters to get relevant results in one call
  </Accordion>
</AccordionGroup>

## Endpoint-Specific Limits

Some endpoints have additional restrictions:

| Endpoint           | Additional Limit                   |
| ------------------ | ---------------------------------- |
| `/recommend`       | Max 20 recommendations per request |
| `/execute_booking` | Max 20 guests per booking          |
| `/inventory`       | Max 50 results per request         |

## Monitoring Usage

### Dashboard

Monitor your API usage in real-time at [privetag.com/developers/usage](https://privetag.com/developers/usage):

* Current minute usage
* Daily quota consumption
* Historical usage graphs
* Alert configuration

### Usage Alerts

Set up alerts to notify you before hitting limits:

1. Go to **API Keys** → **Your Key** → **Alerts**
2. Configure thresholds:
   * 80% of rate limit
   * 90% of daily quota
3. Choose notification method (email, webhook)

## Burst Handling

<Info>
  **Burst Allowance**: We allow brief bursts above your rate limit. If you exceed the limit by up to 20% for less than 5 seconds, requests will be queued rather than rejected.
</Info>

This helps handle legitimate traffic spikes while preventing abuse.

## Rate Limit by Plan

### Free Plan (Development)

* Best for: Testing and development
* 10 requests/minute, 100/day
* No production use

### Basic Plan

* Best for: Small AI agents with moderate traffic
* 60 requests/minute, 1,000/day
* Suitable for: Personal projects, small chatbots

### Premium Plan

* Best for: Production AI applications
* 300 requests/minute, 10,000/day
* Includes: Priority support, usage analytics

### Enterprise Plan

* Best for: High-volume applications
* Unlimited requests
* Includes: Dedicated support, SLA, custom integration

## Requesting Higher Limits

If your application needs higher limits:

1. **Upgrade Plan**: Visit [privetag.com/pricing](https://privetag.com/pricing)
2. **Enterprise**: Contact [enterprise@privetag.com](mailto:enterprise@privetag.com)
3. **Temporary Increase**: Request for special events via support

## Next Steps

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/authentication/api-keys">
    Learn about API key management
  </Card>

  <Card title="Webhooks" icon="webhook" href="/authentication/webhooks">
    Set up event callbacks
  </Card>
</CardGroup>