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

# Rate limits

> Not a published SLA — but real, enforced defaults worth designing around.

Tied doesn't publish a rate-limit contract. It does enforce real limits, though, keyed by IP or by account depending on the endpoint. The numbers below are what you'll actually hit.

<Info>
  These are the enforced limits. They apply in production only.
</Info>

## What's throttled

| Scope | Limit | Window |
| - | - | - |
| Every request, per IP | 3000 | 1 minute |
| Contact search (`/contacts/search`), per account | 100 | 1 minute |
| Reports (v2), per user | 100 | 1 minute |
| Reports (v2), per account | 1000 | 1 minute |
| Conversation transcript, per account | 30 | 1 hour |
| Attachment upload, per account | 60 | 1 hour |
| Account creation, per IP | 50 | 30 minutes |

If you embed the web chat widget, three more throttles apply to traffic your
visitors generate rather than to anything your server calls. All three are keyed
by **visitor IP**:

| Scope | Limit | Window |
| - | - | - |
| `POST /api/v1/widget/conversations` — start a conversation | 6 | 12 hours |
| `PATCH`/`PUT /api/v1/widget/contacts` — update the visitor's contact | 60 | 1 hour |
| `GET /widget` without a `cw_conversation` param — a fresh widget session | 5 | 1 hour |

The first is the one worth knowing about: **six new conversations per IP per 12
hours.** Visitors behind a shared NAT — an office, a school, a large mobile
carrier — share that budget. If that is a problem for your traffic shape, talk to
support rather than working around it client-side.

The global per-IP number is generous enough that a normal integration won't come near it. The ones you can realistically hit are contact search, the reports endpoints, and — if you're pulling transcripts or pushing attachments in bulk — those two hourly account-level throttles.

<Warning>
  Separately, the dashboard's own sign-in, password-reset, and MFA endpoints carry their own tight, IP- and email-keyed throttles — as low as 5 attempts per 5 minutes. Those exist for brute-force protection on the login page, aren't part of the data API, and aren't meant to be called programmatically. If an integration is hitting them, something's calling the wrong endpoint — see [Authentication](/api-reference/authentication).
</Warning>

## What a throttled response looks like

A tripped throttle returns `429` with a **plain-text body**, not the JSON error shape used everywhere else in this API:

```
HTTP/1.1 429 Too Many Requests
Content-Type: text/plain

Retry later
```

<Warning>
  There's no `Retry-After` header. The underlying library supports one, but it's off by default and nothing in the app turns it on. Don't build a client that waits on a header it isn't going to receive — back off on a fixed or exponential schedule instead.
</Warning>

## Sensible client behavior

With no `Retry-After` to read and no published SLA to design against precisely, build for the general case:

<Steps>
  <Step title="Back off on 429, not just on 5xx">
    Treat a 429 as "slow down," not "retry immediately." Exponential backoff with jitter, starting around a second, is the standard shape — and it's the only shape that makes sense without a `Retry-After` value to anchor on.
  </Step>

  <Step title="Don't parallelize list scans">
    Firing 200 concurrent contact-search requests at one account trips the 100/minute throttle long before it hits any real page boundary. Paginate serially, or cap client-side concurrency well under the limits above.
  </Step>

  <Step title="Batch report pulls">
    Polling `/api/v2/accounts/{account_id}/reports` on a schedule? Pull a wider window less often rather than a narrow window constantly — both the per-user and per-account throttles are keyed per minute.
  </Step>

  <Step title="Cache what isn't paginated and doesn't change every second">
    Agents, teams, and canned responses aren't paginated and aren't likely to change between polls. Don't refetch them on a tight loop just because the call happens to be cheap to write.
  </Step>
</Steps>

## Next

<CardGroup cols={2}>
  <Card title="Errors" icon="circle-alert" href="/api-reference/errors">
    Status codes and body shapes for everything that isn't a 429.
  </Card>

  <Card title="Idempotency" icon="repeat-2" href="/api-reference/idempotency">
    What's safe to retry after a backoff — and what isn't.
  </Card>
</CardGroup>


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