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

# Rate Limits

> Understand API request throttling and plan-based usage enforcement

# Rate Limits & Quotas

WazzAPI uses two related controls to protect platform stability and enforce plan limits:

1. **request throttling** on the API
2. **plan-based feature usage limits** such as message, contact, or group capacity

## Request throttling

Default local limits are currently configured for:

* **300 requests/minute per API key**
* **5000 requests/minute global limit**

These values can be adjusted by deployment configuration.

## Headers

When throttling metadata is returned, watch these headers:

| Header                  | Description                                        |
| :---------------------- | :------------------------------------------------- |
| `X-RateLimit-Limit`     | Your maximum request limit for the current window. |
| `X-RateLimit-Remaining` | Requests remaining in the current window.          |
| `X-RateLimit-Reset`     | Unix timestamp when the limit resets.              |

## Handling 429 responses

The API may return `429 Too Many Requests` when you hit either a request throttle or a plan limit.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
```

### Best Practices

1. **Exponential Backoff**: If you hit a limit, wait and retry with increasing delays.
2. **Monitor Headers**: Programmatically check `X-RateLimit-Remaining` to throttle your own requests before hitting the limit.
3. **Queueing**: Smooth burst traffic in your own job system instead of firing large request spikes.

## Plan-based usage limits

The billing layer also enforces feature limits such as:

* message send volume
* contact creation volume
* contact group count
* add-on capabilities like auto warmer

When a plan limit is exceeded, the API returns `429` with a message explaining which limit was reached.