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

# Rate Limits

> EngageFabric API rate limiting by plan tier. Understand request quotas, rate limit headers, retry strategies, and how to upgrade for higher limits.

EngageFabric uses rate limiting to ensure fair usage and protect the platform from abuse.

## Rate Limit Tiers

| Tier           | API Requests | Events/min | WebSocket Connections |
| -------------- | ------------ | ---------- | --------------------- |
| **Free**       | 100/min      | 500/min    | 10                    |
| **Starter**    | 500/min      | 2,500/min  | 50                    |
| **Pro**        | 1,000/min    | 10,000/min | 200                   |
| **Enterprise** | Custom       | Custom     | Custom                |

## Rate Limit Headers

Every API response includes rate limit information:

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

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

***

## Rate Limit Response

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

```json theme={null}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "details": {
      "limit": 100,
      "window": "1 minute",
      "retryAfter": 60
    },
    "requestId": "req-abc123",
    "timestamp": "2025-01-21T10:00:00Z"
  }
}
```

The `Retry-After` header indicates how many seconds to wait:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

***

## Rate Limit Types

### API Rate Limits

Applied per project API key:

```
Tier     Limit
Free     100 requests/minute
Starter  500 requests/minute
Pro      1,000 requests/minute
```

### IP Rate Limits

Applied globally per IP address:

```
10,000 requests/minute per IP
```

<Warning>
  Sharing API keys across multiple clients can quickly exhaust rate limits.
  Use one API key per deployment environment.
</Warning>

### Event Ingestion Limits

Special limits for the `/events` endpoint:

| Tier    | Events/min | Burst |
| ------- | ---------- | ----- |
| Free    | 500        | 50    |
| Starter | 2,500      | 250   |
| Pro     | 10,000     | 1,000 |

Events support burst capacity using a token bucket algorithm.

### WebSocket Limits

| Limit Type                   | Value |
| ---------------------------- | ----- |
| Events per second            | 10    |
| Subscriptions per connection | 50    |
| Message size                 | 64KB  |

***

## Handling Rate Limits

### Retry Strategy

Implement exponential backoff when rate limited:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      const delay = Math.min(
        parseInt(retryAfter) * 1000,
        Math.pow(2, i) * 1000
      );

      console.log(`Rate limited. Waiting ${delay}ms...`);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}
```

### Batch Requests

For events, use batch tracking to reduce API calls:

```javascript theme={null}
// Instead of multiple calls
for (const event of events) {
  await client.events.track(event); // Multiple API calls
}

// Use batch tracking
await client.events.trackBatch(events); // Single API call
```

### Monitor Usage

Track your rate limit usage via response headers:

```javascript theme={null}
const response = await fetch('/api/v1/players', {
  headers: { 'X-API-Key': apiKey }
});

const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');

if (remaining < 10) {
  console.warn('Rate limit almost exhausted');
}
```

***

## Abuse Detection

EngageFabric monitors for abusive patterns:

* Rapid repeated requests
* Unusual event patterns
* Coordinated attacks

Projects exhibiting abuse may be temporarily suspended.

<Note>
  If you believe you've been incorrectly rate limited, contact support with
  your `requestId` for investigation.
</Note>

***

## Increasing Limits

Need higher limits? Options include:

1. **Upgrade your tier**: Higher tiers have increased limits
2. **Enterprise plan**: Custom limits for your needs
3. **Temporary increase**: Contact support for special events

<Card title="Contact Sales" icon="phone" href="mailto:sales@engagefabric.com">
  Need custom rate limits? Contact our sales team
</Card>