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

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

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

В MCP отклонённая или неудачная операция — это обычный результат инструмента с isError: true. В пакете это поле error записи. В talkbar-cli --output 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, и вызов, отменённый вашим клиентом.

Коды ошибок

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 и повторные попытки

{
  "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 мс, если уже идёт выполнение экспорта.

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

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

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

{
  "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.».

Что входит в каждый тариф, см. в разделе Тарифы и лицензия.

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

• Изменения выполняются по одному внутри одного 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.

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

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
• Доступ и разрешения
• talkbar-cli
• Справочник операций