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

# Rate limits and throttling

> How Zerion API rate limits work, which response headers to inspect, how to detect 429 responses, and best practices for retries with exponential backoff.

Rate limits depend on your plan. Visit the [Dashboard](https://dashboard.zerion.io) to view your current limits and usage.

## Monitoring usage

Every API response includes rate limit headers with your current limits and remaining quota. For a full usage breakdown, visit the [Dashboard](https://dashboard.zerion.io) and click **Open Analytics Dashboard**.

| Header | Description |
| - | - |
| `RateLimit-Org-Second-Limit` | Maximum requests allowed per second |
| `RateLimit-Org-Second-Remaining` | Requests remaining in the current second |
| `RateLimit-Org-Second-Reset` | Seconds until the per-second limit resets |
| `RateLimit-Org-Day-Limit` | Maximum requests allowed per day |
| `RateLimit-Org-Day-Remaining` | Requests remaining today |
| `RateLimit-Org-Day-Reset` | Seconds until the daily limit resets |
| `RateLimit-Org-Month-Limit` | Maximum requests allowed per month |
| `RateLimit-Org-Month-Remaining` | Requests remaining this month |
| `RateLimit-Org-Month-Reset` | Seconds until the monthly limit resets |
| `RateLimit-Org-Tier` | Your organization's plan tier name |

## When you hit the limit

The API returns a `429 Too Many Requests` response:

```json theme={null}
{
  "errors": [
    {
      "title": "Too many requests",
      "detail": "Your request had been throttled"
    }
  ]
}
```

## Handling rate limits

Use the `RateLimit-Org-Second-Reset` header to wait the exact time needed before retrying a `429` response. If your day or month quota is exhausted, retrying won't help - check `RateLimit-Org-Day-Remaining` and `RateLimit-Org-Month-Remaining` first.

## Tips to stay under the limit

* **Use webhooks instead of polling** - [transaction subscriptions](/api-reference/subscriptions-to-transactions/create-subscription) give you real-time updates without repeated requests
* **Cache responses** where data doesn't change frequently (e.g., chain lists, token metadata)
* **Use filters and pagination** to fetch only the data you need - smaller requests, fewer calls


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