Rate limits

Limits are counted per credential, not per workspace. Two integrations holding two tokens do not eat into each other’s budget. That is the main reason to issue a separate credential per system rather than sharing one.

Window	Limit
Per minute	600 requests
Per second	60 requests

The per-second ceiling exists so one client cannot burn through the whole minute’s allowance in the first second and lock everyone else out for the remaining fifty-nine.

Headers

Every response carries your current standing, not just the ones that fail:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1786000000

X-RateLimit-Reset is a Unix timestamp in seconds.

When you go over

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests"
  }
}

Retry-After is in seconds and always rounded up, so waiting exactly that long is enough. Rounding down would send you back a fraction early and earn you a second 429.

Handling it

Wait for Retry-After rather than guessing at a backoff. The server already knows when your window resets, and the header is that answer.

async function call(url, options, attempt = 0) {
  const response = await fetch(url, options);

  if (response.status !== 429 || attempt >= 5) return response;

  const wait = Number(response.headers.get("Retry-After") ?? 1);
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));

  return call(url, options, attempt + 1);
}

Watch X-RateLimit-Remaining on the responses you are already getting and slow down before you hit zero. It is cheaper than being throttled.

The chat widget has no credential, so it is limited per origin and per visitor address instead. Anonymous placements are the abuse surface, and they are metered accordingly.

There is no conversation quota

A 429 says you are going too fast and will be fine shortly. No plan caps how many conversations a workspace handles, so there is nothing to run out of and no 402 to handle.

Replies are limited separately

Everything above counts requests. There is a second, unrelated limit on messages that reach a customer, counted per workspace rather than per credential, and it applies however the reply was written: through this API, by an agent in the dashboard, or by the AI. Posting a reply can therefore succeed against these limits and still be held by that one. When it is, the API call still returns normally, the message is still created, and an internal note on the conversation explains that it was not delivered. See Sending limits for the numbers and for what a held reply looks like.

Getting started

Core concepts

Headers

When you go over

Handling it

The widget is limited differently

There is no conversation quota

Replies are limited separately

​Headers

​When you go over

​Handling it

​The widget is limited differently

​There is no conversation quota

​Replies are limited separately

Headers

When you go over

Handling it

The widget is limited differently

There is no conversation quota

Replies are limited separately