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

# Rate Limiting

> How API rate limits work and how to handle 429 responses.

API rate limits are in place to protect the Heyy API from traffic spikes that could put our systems at risk. We measure the number of requests sent to the API and throttle when they exceed the allowed amount. When you exceed the limit, we respond with **429 Too Many Requests** and include the following headers:

<table style={{ tableLayout: 'auto' }}>
  <thead>
    <tr>
      <th style={{ whiteSpace: 'nowrap' }}>Header Name</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td style={{ whiteSpace: 'nowrap' }}><code>X-RateLimit-Limit</code></td>
      <td>Maximum number of requests allowed for the app.</td>
    </tr>

    <tr>
      <td style={{ whiteSpace: 'nowrap' }}><code>X-RateLimit-Remaining</code></td>
      <td>Number of requests left in the current minute.</td>
    </tr>

    <tr>
      <td style={{ whiteSpace: 'nowrap' }}><code>X-RateLimit-Reset</code></td>
      <td>Time when the request count resets to the maximum. Shown as a UNIX timestamp.</td>
    </tr>
  </tbody>
</table>

## Rate limits by plan

Limits are applied per **1-minute** window. The table below shows the maximum number of requests allowed per minute for each plan.

| Plan       | Requests per minute |
| ---------- | ------------------- |
| Hobby      | 100                 |
| Pro        | 500                 |
| Ultra      | 1,000               |
| Enterprise | Custom              |

## Error response example

When you are rate limited, the API returns **429 Too Many Requests** with this body:

```json theme={null}
{
  "success": false,
  "error": {
    "messageKey": "rate_limit_exceeded",
    "message": "Too many requests. Limit is applied per minute per tenant. Please retry after the time indicated by the X-RateLimit-Reset header."
  }
}
```

Use the `X-RateLimit-Reset` header to know when you can send requests again, and consider implementing exponential backoff or queuing to avoid hitting the limit repeatedly.