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

# Rate Limits

> Understand the API rate limits and how to handle them.

# Rate Limits

The Zeplo API enforces rate limits to ensure fair usage and platform stability.

## Rate limit headers

Every API response includes rate limit headers:

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

## Default limits

| Scope | Limit | Window |
| - | - | - |
| Session-based (per user) | 100 requests | 1 minute |
| API Key (configurable) | Per-key setting | 1 minute |
| API Key (monthly) | Per-key setting | Monthly |
| Webhook endpoints | 1000 requests | 1 minute |

## Configuring API key limits

When creating an API key, specify the rate and monthly limits:

```json theme={null}
{
  "rateLimit": 100,
  "monthlyLimit": 10000
}
```

## Rate limit exceeded

When you exceed the rate limit, the API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 100 requests per minute. Please try again later.",
  "retryAfter": 45
}
```

### Best practices

* Implement exponential backoff when receiving `429` responses
* Cache responses where possible to reduce API calls
* Use bulk endpoints (e.g., bulk contact import) instead of individual calls
* Monitor the `X-RateLimit-Remaining` header to throttle proactively


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.