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

# Rate limits

> Published limits, the headers that tell you where you stand, and how to back off.

Every response from the public API carries rate-limit headers, so you never
have to discover a limit by hitting it.

## Limits

Limits are applied per API key. Requests authenticated without a key fall back
to a per-IP bucket (collapsed to a `/64` for IPv6 clients).

| Bucket | Applies to | Limit |
| - | - | - |
| Global | Every public API request | **600 requests / minute** |
| Write | `POST`, `PUT`, `PATCH`, `DELETE` | **120 requests / minute** |

Writes count against both buckets. A write rejected by the write bucket does
**not** consume global budget — one over-limit request produces exactly one
rejection.

<Note>
  These limits are generous by design and are not a billing control. Metered
  usage — meeting minutes and LLM tokens — is governed by your plan, not by
  these limits. Need a higher ceiling for a launch or a backfill? Contact us
  before you need it, not during.
</Note>

## Headers

Present on every public API response, not just 429s.

| Header | Meaning |
| - | - |
| `RateLimit-Limit` | Requests allowed in the current window |
| `RateLimit-Remaining` | Requests left in the current window |
| `RateLimit-Reset` | Seconds until the window resets |
| `X-RateLimit-Limit` | Legacy alias of `RateLimit-Limit` |
| `X-RateLimit-Remaining` | Legacy alias of `RateLimit-Remaining` |
| `X-RateLimit-Reset` | Legacy alias of `RateLimit-Reset` |
| `Retry-After` | **429 only.** Seconds to wait before retrying |
| `X-Request-Id` | Request id, on every response |

```bash theme={null}
curl -sD - -o /dev/null https://api.waterr.ai/v1/scenarios \
  -H "Authorization: Bearer wai_your_key" | grep -i ratelimit
```

```
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 41
```

## When you're limited

A 429 returns the standard [error envelope](/api-reference/errors) with
`error.type` of `rate_limit_error`:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry in 23s.",
    "doc_url": "https://docs.waterr.ai/api-reference/errors#rate_limited"
  },
  "details": "Limit is 600 requests per 60s on the global bucket. See https://docs.waterr.ai/api-reference/rate-limits",
  "request_id": "req_...",
  "status": "error",
  "message": "Too many requests. Retry in 23s."
}
```

Always prefer the `Retry-After` header over a fixed sleep — it reflects the
actual remaining window rather than a guess.

<CodeGroup>
  ```python Python theme={null}
  import time, httpx

  def with_retry(client, method, url, **kwargs):
      for attempt in range(6):
          r = client.request(method, url, **kwargs)
          if r.status_code != 429:
              return r
          time.sleep(int(r.headers.get("Retry-After", 2 ** attempt)))
      return r
  ```

  ```javascript Node theme={null}
  async function withRetry(url, init = {}, attempt = 0) {
    const res = await fetch(url, init);
    if (res.status !== 429 || attempt > 5) return res;

    const wait = Number(res.headers.get("Retry-After") || 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return withRetry(url, init, attempt + 1);
  }
  ```
</CodeGroup>

## Staying under the limit

* **Watch `RateLimit-Remaining`** and slow down before you hit zero, rather
  than sprinting into a 429 and backing off.
* **Prefer webhooks over polling.** Nearly every polling loop we see is
  waiting for a meeting to end or an analysis to land — both of which are
  [webhook events](/api-reference/webhooks) (`meeting.ended`,
  `session.analysis_complete`). One subscription replaces thousands of
  requests.
* **Bucket by key, not by process.** Limits are per API key, so ten workers
  sharing one key share one budget. Issue a key per workload if you want them
  isolated.


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