Rate limits

The API is rate limited per account to keep the platform fast and fair for everyone. A well-behaved client almost never notices a limit; a client that loops a single read thousands of times in a tight loop will. When you exceed a limit, the API responds with 429 Too Many Requests.

How 429 works

A 429 is not an error in your payload — your request was well-formed, you simply asked for too much, too fast. It carries the standard error shape:

{
  "error": "rate_limited",
  "message": "Too many requests. Retry after a short backoff."
}

The correct response to a 429 is always the same: wait, then retry the same request. A 429 is transient and safe to retry — unlike a 400, which will fail identically until you fix the request.

Back off with exponential delay and jitter

Retry on a growing delay, and add jitter — a small random offset — so that many clients (or many retries) don't all wake up and retry at the same instant and re-collide. Exponential growth keeps you from hammering the API; jitter spreads the herd.

async function withRetry(fn: () => Promise<Response>, tries = 5): Promise<Response> {
  for (let i = 0; i < tries; i++) {
    const res = await fn();
    if (res.status !== 429) return res;
    // exponential base (250ms, 500ms, 1s, 2s, …) + up to 250ms of jitter
    const delay = 2 ** i * 250 + Math.random() * 250;
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error('still rate limited after retries');
}

import random, time, requests

def with_retry(make_request, tries=5):
    for i in range(tries):
        res = make_request()
        if res.status_code != 429:
            return res
        # exponential base (0.25s, 0.5s, 1s, 2s, …) + up to 0.25s of jitter
        time.sleep(2 ** i * 0.25 + random.random() * 0.25)
    raise RuntimeError("still rate limited after retries")

Cap the number of retries (the snippets above stop after five) so a sustained limit surfaces as a real error instead of hanging your job forever.

Stay under the limit in the first place

Backoff is the safety net. The cheaper fix is to make fewer, larger requests:

• Batch. Where an endpoint accepts a list or returns a page, ask for many items in one call instead of looping one request per item. Paginate with a generous limit rather than fetching one row at a time — see Pagination.
• Cache. Reads that change slowly (configuration, link metadata, segment definitions) can be fetched once and reused. Re-fetch on a sensible interval or when you make a write that would change them, not on every iteration of a loop.
• Poll politely. If you watch a value for changes, poll on an interval with backoff, not in a busy loop. Most data does not change second to second.
• Spread bursts. A nightly job that fires thousands of requests in one second will trip the limiter; the same job spread over a few seconds will not.

Fan-message pacing is a separate, fixed safety mechanism

Do not confuse the API rate limit with how fast your outbound fan messages are delivered. They are unrelated systems with opposite purposes.

When you build, preview, and schedule a broadcast, the API accepts it quickly. The actual delivery to fans is then released on a deliberately conservative, account-safe cadence that cannot be sped up — there is no priority flag, no "send now," and no parameter that shortens it. This pacing is the point: it is what keeps a connected account in good standing.

Next steps

• Response structure — the 429 body and status table.
• Chat & broadcasts — how scheduling and safe pacing work.
• Security — how the perimeter and per-account limits are enforced.
• FAQ — quick answers on limits, safety, and keys.