Rate limits

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.

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.

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

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 with error.type of rate_limit_error:

{
  "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.

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

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);
}

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 (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.

Getting Started

Meetings

Personas

Scenarios

Embed Scenario

Memory

Post-Meeting Data

Goals

Avatars

Voices

Tools

Guardrails

Meeting Skills

Users

Guides

Integrations

Agent Skills

Limits

Headers

When you’re limited

Staying under the limit

​Limits

​Headers

​When you’re limited

​Staying under the limit

Limits

Headers

When you’re limited

Staying under the limit