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

# Limits and errors

> Rate limits, page sizes, latency, error codes and when to retry.

## Rate limits

Every tool is rate limited per workspace:

| Window | Limit |
| - | - |
| 5 seconds | 30 requests |
| 1 minute | 60 requests |
| 1 day | 1,000 requests |

The budget is shared by everyone and every agent working in the workspace, and some tools spend more than one unit per call, so parallel sessions can trip a window sooner than these numbers suggest. When a read is refused for rate, some tools still answer with the affected fields null and a retryable gap rather than an error.

A `rate_limit_exceeded` error carries a `Retry-After` header naming the window you tripped. Wait that long. Do not guess a backoff.

[`get_workspace_overview`](https://heybtw.com/docs/tools/get-workspace-overview) makes three internal reads per call and spends three units of a shared internal budget, so at most about 20 overviews fit in a minute. Call it once at the start of a session, not before every question.

## Page sizes and caps

Each reference page states its tool's limits. The common shapes:

* **Cursor paging.** Tools with `cursor` return `metadata.pagination` with `has_more` and `next_cursor`. Pass `next_cursor` back with the same other arguments. Cursors expire after 15 minutes.
* **Bounded results.** Tools without a cursor cap their rows and say so with a `scope_truncated` gap whose `what_to_do` names the parameters that narrow the query. Narrow the query; retrying the same call returns the same result.
* **Batch inputs.** Tools that take people take at most 500 per call. Larger lists go in chunks against one preview (`action: "append"` with the same token).

## Latency

Most reads answer in 1 to 5 seconds. Program-wide reads take longer: [`get_program_report`](https://heybtw.com/docs/tools/get-program-report) and [`get_invite_recommendations`](https://heybtw.com/docs/tools/get-invite-recommendations) can take 7 to 9 seconds, and the first call of a session about 5.

## Error codes

A failed call returns `status: "error"`, `data: null` and an `error` object with the same fields as a gap: `code`, `message`, `what_failed`, `what_to_check`, `what_to_do`, `retryable`. A failed read is always an error, never an empty result.

| Code | Meaning | What to do |
| - | - | - |
| `invalid_parameter` | A parameter is missing, malformed or not supported. | Fix what `what_failed` names. |
| `entity_not_found` | No collab, List or record with that id or name that this workspace can see. | Check the id with [`list_events`](https://heybtw.com/docs/tools/list-events) or [`get_lists`](https://heybtw.com/docs/tools/get-lists). |
| `scope_truncated` | The query was valid but a server bound cut it short. Appears as a gap. | Narrow with the parameters `what_to_do` names. |
| `rate_limit_exceeded` | A rate window was tripped. | Wait for `Retry-After`. |
| `query_timeout` | The query ran out of time. Retryable. | Retry with a narrower query. |
| `upstream_crm_error` | The CRM connected inside heyBTW did not answer for some rows. | Treat those rows as unknown. Retry in a few minutes. |
| `insufficient_scope` | The sign-in lacks write access. | Reconnect and approve write access on the consent screen. |
| `entitlement_required` | The workspace's plan lacks the feature. | Tell the user; heyBTW support can help. |
| `internal_error` | Something failed on heyBTW's side. | Retry once. If it repeats, tell the user and include the error. |

## When to retry

* **Reads:** retry once on `internal_error` or any error with `retryable: true`. Never retry a non-retryable gap: the answer will not change.
* **Writes:** retry only with the **same** `client_request_id`. A write that already went through replays its first answer and is never repeated. A new id is a new write.
* **Sends:** never resend a Luma invite or a partner invitation to "check". Read the send's status instead ([`activate_list`](https://heybtw.com/docs/tools/activate-list) `action: "status"`, [`manage_collab_partners`](https://heybtw.com/docs/tools/manage-collab-partners) `action: "status"`).


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