Errors

Something in the request is not valid: an unknown, repeated or out-of-range query parameter, a query string or body on an endpoint that takes none, a cursor issued for another endpoint, filter or team, a malformed Totem-Team header, or a body that is not the JSON this endpoint expects. param names the parameter, header or field at fault. A conversations cursor is also refused once the conversation it points at has been erased.

Correct what param names before you retry: the same request fails the same way. For a cursor, send the next_cursor you received from the same endpoint, with the same filters and team. If a conversations cursor you did not change is refused, start that list again from the first page.

The key reads more than one team and this endpoint reads one team's data, but the request does not say which team.

Send the team's id (team_…, as listed by GET /v1/teams) in the Totem-Team header.

The request carried a secret key together with an Origin header, which means it came from a browser. Totem refuses it before reading anything.

Call the API only from your server. If the key has been in a web page, a mobile app or a browser extension, treat it as leaked: roll it and mark it as compromised, so the old key stops working at once.

The Authorization header is missing or malformed, or the key is unknown, wrong or revoked, or its integration is no longer active.

Send Authorization: Bearer <key> with a current secret key. Do not retry in a loop: repeated failures from one IP address, or against one key, lock it out for a while with 429 rate_limited.

The key was rolled and its grace period is over.

Deploy the key that replaced it: the old key is past its grace period and will not work again. If there is no replacement, create a new key in Settings → Developers.

The key lacks a permission this endpoint needs. Every v1.0a key holds the full read set, so this should not happen.

Contact support and quote the Totem-Request-Id of the response.

The organization's plan does not include the Totem API at the moment.

Keep your data and cursors, and pause calls until the customer has a plan with API access again; then continue where you left off. While access is refused, the feed delivers nothing for the key's teams, removals included: if the refusal lasts longer than your retention policy allows, delete your copy.

The key is valid, but the request came from an IP address outside the integration's allowlist.

Call from an allowed address, or ask an administrator to add yours to the allowlist in Settings → Developers.

The team is restricted for now: it is disabled (for example, suspended for non-payment), archived or billing-only, or its API access is paused. GET /v1/teams still lists it.

Keep the team's data and cursor, skip it for this run and try again later. The key's other teams are not affected. While the team is restricted, the feed delivers nothing for it, removals included: if the restriction lasts longer than your retention policy allows, delete the team's copy.

Totem does not export this team's data through the API because the team works in a sensitive sector, such as health care, where its records can reveal health information.

Skip the team: waiting does not change this. The feed delivers nothing for it, removals included, so keep what you already have only as long as your retention policy allows, then delete the team's copy. Talk to the customer or to Totem if you need its data.

Totem has temporarily switched this endpoint off for every key.

Keep your data and cursors and try again later; the other endpoints keep working.

The record does not exist, was removed, belongs to a team this key does not read, or was created so recently that Totem has not prepared it yet. A GET or POST under /v1/ that matches no endpoint also gets this code. Any other method, and any path outside /v1/, gets a plain 404 from the firewall in front of the API, with no problem body and no Totem-Request-Id.

Check the id and the path. If the record was created moments ago, do not retry in a loop: the changes feed delivers it as soon as it is ready.

The Totem-Team header names a team this key does not read: one it never covered, one removed from the key or from the organization, or one that was deleted. Without the header, it means the key no longer reads any team.

Re-read GET /v1/teams before you act. If the team is no longer listed, delete its copy and its cursor; if it is still listed, keep everything and try again on the next run.

Totem cannot continue the feed from this cursor: the data was restored from a backup, or a gap was found in the team's changes.

Run a full resync: forget the versions you stored for the team, read the feed again without a cursor, and once it has caught up delete every local record of the team it did not deliver. Keep using your current copy until then.

Totem is still preparing this team's data for the API. This happens once per team, after it is first added to any key; adding it to another key later does not repeat it.

Keep whatever you hold for the team and try again in a few minutes; the key's other teams keep syncing meanwhile.

The cursor is more than 30 days old, counted from the point in the feed it reached (or, while an initial sync is still running, from when that sync started).

Run a full resync, as for resync_required. To prevent it, save the next_cursor of every page, empty pages included: the cursor of a team you poll regularly never ages out.

The key went over its rate limit (items per minute), or too many failed authentication attempts from this IP address or against this key have locked it out for a while.

Wait the seconds in Retry-After, then retry the same request. Each request sets aside its full limit up front and gives back what it does not use, so a smaller limit keeps a nearly spent allowance moving.

The key has spent its daily quota of items. Every item returned by the changes feed and by every list counts toward it, including GET /v1/teams, GET /v1/members, GET /v1/booking_services and a lead's activities. The quota resets at 00:00 UTC.

Stop syncing until 00:00 UTC (Retry-After counts the seconds) and resume then with the same cursor: nothing is lost. Requests for one record, such as GET /v1/leads/{id}, search and GET /v1/me do not count toward the quota and keep working.

Something went wrong inside Totem while answering this request.

Retry with exponential backoff. If it keeps failing, contact support and quote the Totem-Request-Id.

Totem has temporarily switched the API off for every key.

Keep your data and cursors and retry later with exponential backoff.

Reserved: the API itself does not return this code today. A 503 from the load balancer or the hosting platform in front of the API arrives without a problem body; treat it like this code.

Retry with exponential backoff; your data and cursors stay valid.