# Ошибки и ограничения

Коды ошибок TalkBar MCP и talkbar-cli и что с ними делать, лимиты тарифа, параллельная работа, правила для аргументов и безопасные повторы.

Canonical URL: https://docs.talkbar.ru/mcp/errors-and-limits


Когда операция отклонена или завершилась ошибкой, TalkBar отвечает коротким кодом и предложением о том, что нужно изменить. Ассистентам и скриптам следует ориентироваться на код; предложение предназначено для людей. На этой странице перечислены все коды и правила, которые за ними стоят.

## Формат ошибки

В MCP отклонённая или неудачная операция — это обычный результат инструмента с `isError: true`. В пакете это поле `error` записи. В `talkbar-cli --output json` ошибка выводится на стандартный вывод. Формат везде одинаковый:

```json
{
  "error": {
    "code": "invalid_arguments",
    "message": "notes.create does not take `content`. Note text goes in markdown. It takes: markdown, pinned, projectId, sessionIds, title, workspaceId. Arguments: talkbar_tools {\"tool\":\"notes.create\"}"
  }
}
```

Некоторые коды добавляют поля, перечисленные ниже. Ошибку протокола JSON-RPC вместо этого получают только вызов инструмента с именем, отличным от [пяти инструментов MCP](/mcp/tools), и вызов, отменённый вашим клиентом.

## Коды ошибок

| Код | Что означает | Что делать |
| --- | --- | --- |
| `invalid_arguments` | Неверен сам запрос: неизвестный аргумент, неверный тип, значение вне диапазона или не из списка допустимых, отсутствует обязательный аргумент, пустой идентификатор. | Измените запрос. В сообщении назван аргумент; `talkbar_tools {"tool": "<id>"}` или `talkbar-cli tools info <id>` показывает, что принимает операция. |
| `not_found` | Идентификатор неизвестен, относится к другому пространству или элемент находится в корзине. Также неизвестное имя операции. | Найдите нужный идентификатор с помощью `talkbar_find` или списка. Если элемент в корзине, в сообщении будет «… is in the Trash; restore it first». |
| `turned_off` | Вы выключили операцию в разделе **Настройки → Доступ по MCP**, или MCP выключен. Только для MCP. | Попросите пользователя включить её. Повтор вызова не поможет. |
| `failed` | Запрос составлен правильно, но текущее состояние элемента не позволяет его выполнить (например, «A topic with this name already exists»), его блокирует правило администратора или внутри TalkBar что-то пошло не так. | Прочитайте сообщение. Измените состояние элемента или запрос; не повторяйте тот же вызов без изменений. |
| `declined` | Пользователь не подтвердил вызов `talkbar_delete` или не ответил в течение 5 минут. Ничего не выполнено. | Не повторяйте сами. Спросите пользователя, чего он хочет. |
| `confirmation_unavailable` | Вызов `talkbar_delete` пришёл от клиента, который не умеет спрашивать пользователя, а **Разрешить удаление без подтверждения** выключено. Ничего не выполнено. | Используйте клиент, который поддерживает запросы к пользователю по MCP (`elicitation`), или попросите пользователя изменить параметр. |
| `busy` | Другое изменение успело обратиться к базе данных раньше, или уже идёт выполнение экспорта. Содержит `"retryable": true` и `retryAfterMs`. | Подождите `retryAfterMs` и отправьте тот же вызов снова. Если вызов что-то создавал, сначала проверьте, что этого ещё нет. |
| `conflict` | `notes.update` отправлен с `expectedUpdatedAt`, которого у заметки уже нет: кто-то изменил её после того, как вы её прочитали. Содержит текущий `updatedAt` заметки. | Прочитайте заметку заново с помощью `notes.get` и внесите правку в её текущее содержимое. |
| `session_recording` | Сессия ещё записывается. Возвращается для `sessions.trash`, изменений участников (`sessions.speakers.rename`, `.link`, `.unlink`) и `exports.enqueue`. | Повторите после окончания записи, когда `sessions.recording` перестанет её возвращать. |
| `limit_reached` | Фиксированное ограничение самого элемента, а не тарифа. Содержит `limit` и `max`. Сейчас это: в сессии не больше 24 карточек знаний (`"limit": "sessionCards"`). | Сначала освободите место, например уберите карточку с помощью `sessions.cards.detach`. |
| `plan_limit` | Ваш тариф TalkBar этого не позволяет. Содержит `limit`, а для лимитов по количеству — `max`, `used` и `plan`. | Освободите место или перейдите на тариф выше в приложении. Повтор не поможет. См. [Лимиты тарифа](#лимиты-тарифа). |

### `invalid_arguments` или `failed`?

- `invalid_arguments` означает, что нужно изменить запрос: неверное значение, неизвестный тип или цвет, пустое название.
- `failed` означает, что запрос в порядке, но текущее состояние элемента не позволяет его выполнить: «A topic with this name already exists», «A series with this id already exists; use another id or change the existing one», «Archived series cannot take new sessions».

### `busy` и повторные попытки

```json
{
  "error": {
    "code": "busy",
    "message": "TalkBar's database was busy with another write. Try the same call again; if it created something, check first that it is not already there.",
    "retryable": true,
    "retryAfterMs": 1000
  }
}
```

`retryAfterMs` равен 1 000 мс, если база данных была занята, и 5 000 мс, если уже идёт выполнение экспорта.

## Лимиты тарифа

Большинство действий ассистента тарифом не ограничены. Ограничены эти операции, потому что они увеличивают количество, которое ограничивает ваш тариф:

| Операция | `limit` | Что учитывается |
| --- | --- | --- |
| `projects.create`, `projects.restore` | `projects` | Проекты в пространстве, с которым работает вызов |
| `sessions.restore` | `sessions` | Хранящиеся сессии в этом пространстве |

При достижении лимита вызов отклоняется:

```json
{
  "error": {
    "code": "plan_limit",
    "limit": "projects",
    "max": 1,
    "used": 1,
    "plan": "free",
    "message": "Project limit reached (1 of 1 on Free): your plan includes 1 project, and this workspace already has 1. Move a project to Trash or upgrade the plan in TalkBar, then try again; plan.get lists the plans above Free."
  }
}
```

- Тариф определяется лицензией, активированной в приложении. Ассистент не может его изменить.
- `plan.get` сообщает тариф, каждый лимит с текущим использованием и тарифы выше текущего.
- На Business, самом старшем тарифе, сообщение заканчивается фразой «Move a project to Trash, then try again.».

Что входит в каждый тариф, см. в разделе [Тарифы и лицензия](/data/plans-and-license).

## Параллельная работа

- **Изменения выполняются по одному** внутри одного MCP-сервера или процесса `talkbar-cli`, поэтому параллельные вызовы одного ассистента никогда не конфликтуют. Чтение выполняется параллельно.
- **Другие процессы:** когда записывает другая программа (приложение во время записи сессии или второй MCP-сервер), изменение ждёт её до 5 секунд, а затем отвечает `busy`.
- **Экспорт:** `exports.run` выполняется вне этой очереди, потому что доставка может занимать много времени и не должна задерживать `exports.cancel`. На одном сервере одновременно выполняется только один экспорт; второй отвечает `busy`.
- **До четырёх вызовов одновременно:** одно MCP-подключение выполняет не больше четырёх вызовов инструментов одновременно. Ответы могут приходить не в том порядке, что запросы.
- **Отменённые запросы:** когда клиент отменяет вызов, он получает ошибку JSON-RPC (`-32603`, «Request cancelled by the client»), а не код ошибки с этой страницы. Запрос, отменённый до начала, не выполняется, а изменение, которое ещё ждало своей очереди, отбрасывается. Если вы выключите операцию, пока изменение ждёт, оно ответит `turned_off`.

Одно долго работающее MCP-подключение быстрее, чем запуск `talkbar-cli` для каждого вызова. В командной строке лучше использовать [`tools batch`](/mcp/cli#запуск-пакета).

## Правила для аргументов

TalkBar строго проверяет аргументы, поэтому ошибка называется явно, а не игнорируется молча:

- **Неизвестные аргументы отклоняются с указанием имени** и списка аргументов, которые принимает операция. Если текст заметки передан в `content`, `text` или `body`, приходит подсказка «Note text goes in markdown.». Неизвестные ключи внутри вложенного объекта, описанного в схеме, тоже отклоняются.
- **Неверные значения отклоняются до поиска.** Неверный тип, значение не из списка допустимых или вне диапазона либо неверный элемент массива дают `invalid_arguments` ещё до того, как TalkBar начнёт искать идентификаторы. Поэтому при неизвестном идентификаторе и неверном значении будет названо значение; при верном значении и неизвестном идентификаторе — `not_found`.
- **Отсутствующие обязательные аргументы** называются следующими (`noteId is required`), тоже до поиска.
- **Точные значения.** Допустимые значения должны совпадать точно: `"Note"` или `" any "` отклоняются там, где ожидается `note` или `any`.
- **Диапазоны не подгоняются.** `limit`, `maxChars` или `offset` вне диапазона из схемы отклоняются.
- **Идентификаторы не могут быть пустыми.** Аргумент, имя которого оканчивается на `Id`, если он передан, не может быть `""`; чтобы очистить необязательный, используйте `null`. Список, имя которого оканчивается на `Ids`, не может содержать пустой идентификатор.
- **Никаких управляющих символов** ни в одном аргументе, кроме табуляции и переводов строки.
- **`args` — это объект.** Если аргументов нет, не передавайте его или передайте `null`; массив, число или строка отклоняются с сообщением «arguments must be an object».
- **Названия, которые не могут быть пустыми,** проверяются после удаления пробелов по краям, поэтому `"   "` считается пустым. Заметки, названия чатов и имя в профиле могут быть пустыми, как в приложении.
- **Время в прошлом** принимается там, где его принимает приложение, например при добавлении встречи, которая уже прошла.
- **Пять инструментов MCP** отклоняют ключи, которых не принимают. `talkbar_read`, `talkbar_change` и `talkbar_delete` принимают `tool` (с `args`) или `calls`, но не оба сразу, а `stopOnError` должен быть `true` или `false`.

## Безопасное повторение изменений

Отправить одно и то же изменение дважды безопасно. Повторный вызов тоже завершается успешно и сообщает текущее состояние:

- Перемещение в корзину того, что уже в корзине, или восстановление того, что не в корзине.
- Архивация того, что уже в архиве, или разархивация того, что не в архиве.
- Закрепление того, что уже закреплено.

Сохраняется дата первого перемещения в корзину или архивации. Неизвестный идентификатор по-прежнему даёт `not_found`.

Исключение — `action_items.remove`: эта операция удаляет задачу окончательно (добавленная вами задача удаляется, задача из итогов скрывается), поэтому повторное удаление даёт `not_found`.

Создание повторять небезопасно: два вызова `notes.create` создадут две заметки. Если на создание пришёл ответ `busy`, проверьте результат, прежде чем отправлять вызов снова.

## Что недоступно никогда

Что бы вы ни включили, ассистент не может вести запись или управлять текущей сессией, изменять транскрипт, подводить итоги, запускать ИИ-функции TalkBar, менять настройки, удалять что-либо навсегда, очищать корзину, добавлять или переиндексировать документы. Кода ошибки для этого нет: таких операций просто не существует.

## См. также

- [Пять инструментов MCP](/mcp/tools)
- [Доступ и разрешения](/mcp/access-and-permissions)
- [talkbar-cli](/mcp/cli)
- [Справочник операций](/mcp/operations)