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

# Rate limits

> Per-organization request budget across three windows. How to detect, back off, and avoid hitting them.

Rate limits are enforced **per organization** across three windows:

| Window             | Limit           |
| ------------------ | --------------- |
| Per second (burst) | 3 requests      |
| Per minute         | 200 requests    |
| Per month          | 50,000 requests |

All three apply at once. The **first window you exceed** returns `429 Too Many Requests` with a `Retry-After` header telling you how long to wait for that window to reset.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1750684800
X-RateLimit-Monthly-Remaining: 41280
```

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded. Retry after 23 seconds.",
    "code": "BAD_REQUEST"
  }
}
```

## Response headers

These headers are present on **both successful and `429` responses**, so you can track your remaining budget without waiting to get throttled:

* `X-RateLimit-Limit` — the per-minute ceiling.
* `X-RateLimit-Remaining` — requests left in the current minute window (`0` on a per-minute `429`).
* `X-RateLimit-Reset` — Unix timestamp (seconds) when the minute window resets.
* `X-RateLimit-Monthly-Remaining` — requests left in your monthly quota.

The `429` response additionally carries `Retry-After` — seconds to wait before retrying. Use this value, don't hardcode delays.

## Weighted cost

Most endpoints cost **1 request** against every window.

The exception is **launching a sequence** (`POST /sequences/{id}/launch`): it charges your **monthly** quota proportionally to the number of contacts enqueued. Enrolling 5,000 leads consumes roughly 5,000 monthly units — so bulk enrollment is **not "free."** The per-second and per-minute windows still count a launch as a single request; only the monthly quota is charged the weighted cost. This weighting applies to **all channels**, including WhatsApp sequences — the cost is the number of enqueued contacts.

Sending a one-off WhatsApp message (`POST /whatsapp/send`) costs **1 monthly unit** per message, like any ordinary request — it is not weighted.

<Tip>Check `X-RateLimit-Monthly-Remaining` before a large launch. If you have 41,280 monthly requests left and try to enroll 50,000 leads, the launch will exhaust your monthly quota.</Tip>

## Exemptions

Some organizations are **not subject to these limits**:

* Organizations on the **lifetime** plan.
* Any organization an administrator has **explicitly exempted**.

Exempt organizations may also be configured with **custom limits** (higher per-second / per-minute / monthly ceilings) instead of being fully unlimited.

## Best practices

<Tip>**Honor `Retry-After`**. Pause for that many seconds, then retry the exact same request.</Tip>

* **Spread bulk operations.** At 200 requests/minute you can sustainably push \~3 requests/second; aim to stay under the per-second burst of 3 to leave headroom.
* **Watch the monthly quota.** 50,000 requests/month is shared across the whole organization, and sequence launches draw down that quota by the number of contacts enrolled. Budget accordingly.
* **Cache catalog lookups** (`/lead-sources`, `/pipeline/stages`, `/webhooks/events`) instead of hitting them on every request — they change rarely.
* **Batch reads with the `query` filter** instead of N individual `GET /leads/{id}` calls when you need to look up several leads.

## When you hit the wall

If your integration legitimately needs more than the default budget provides, contact [soporte@flowestate.app](mailto:soporte@flowestate.app) — organizations can be exempted or configured with custom limits on a per-organization basis.