Skip to Content
Card SDKСправочник APIОшибки и лимиты

Ошибки и лимиты

CardSdkError

Любой отказ — от приложения или от собственных проверок SDK ещё до того, как запрос покинет карточку, — это CardSdkError:

import { CardSdkError, isCardSdkError } from '@neurosquad/card-sdk' async function saveReport(text: string): Promise<void> { try { await card.fs.writeText('reports/latest.md', text, { createDirs: true }) } catch (error) { if (isCardSdkError(error, 'PERMISSION_DENIED')) { card.ui.toast(`This needs the ${error.permission} permission`) } else if (isCardSdkError(error, 'RATE_LIMITED')) { await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 1000)) return saveReport(text) } else if (error instanceof CardSdkError) { card.log.error(error.code, error.method, error.hostMessage, error.data) } else { throw error } } }
СвойствоЧто это
codeОдин из кодов ниже.
messagemethod: host message [CODE] — hint, готово для журнала.
hostMessageТолько сообщение приложения (по-английски, для разработчиков — пользователям показывайте свой текст).
methodМетод, который упал, если ошибка пришла из вызова.
dataПодробности: ошибки схемы, { permission }, { retryAfterMs }, { conflict }…
hintПодсказка в одну строку — для кодов, у которых она есть.
permissionДля PERMISSION_DENIED: недостающее разрешение.
retryAfterMsДля RATE_LIMITED: сколько ждать.
issuesДля INVALID_PARAMS / BAD_REQUEST: { path, keyword, message }[] — где параметры не совпали со схемой.

isCardSdkError(error, code?) — защитник типа, при желании для одного кода.

Коды ошибок

КодЗначитОбычно
BAD_REQUESTСообщение повреждено или его параметры — не простой JSON.В параметрах Date, Map или экземпляр класса — передавайте простые данные.
INVALID_PARAMSПараметры не подходят под схему метода.Точный путь — в error.issues. А также значение порта, не прошедшее схему, или незаданный {{secret:…}}.
METHOD_NOT_FOUNDПриложение не знает этот метод.Старое приложение — проверяйте через card.host.supports().
PERMISSION_DENIEDУ пакета нет разрешения.Объявите его в манифесте или, если оно необязательное, попросите через card.permissions.request().
NOT_CONNECTEDЦелевая карточка или агент не соединены с вашей стрелкой.Попросите пользователя её провести.
NOT_FOUNDНет такой карточки, агента, ключа, файла или порта.
QUOTA_EXCEEDEDКвота исчерпана: байты или ключи хранилища, созданные карточки, наблюдатели за файлами, полная очередь промптов агента.Удалите старые данные, остановите старых наблюдателей, подождите.
RATE_LIMITEDСлишком много вызовов. Сколько ждать — в data.retryAfterMs.Объединяйте вызовы, откладывайте, отступайте. (Заголовок, статус, бейдж, обзор и внимание из-за этого никогда не отклоняются — SDK схлопывает и повторяет их.)
TOO_LARGEСообщение, значение или ответ больше лимита.См. Лимиты.
TIMEOUTНет ответа вовремя (запрос к порту, команда, сетевой запрос).
BUDGET_PAUSEDВоркспейс вышел за бюджет; программные промпты отклоняются.Пользователь поднимает лимит в карточке Budget.
BUSYАгент посреди хода, а вы указали whenBusy: 'fail'.
HOST_NOT_ALLOWEDnet.fetch к хосту вне выданных или к хосту, который резолвится в заблокированный адрес.Добавьте хост в разрешение network.
NETWORK_ERRORСбой DNS, соединения, TLS или потока.
FS_DENIEDПуть вне папки воркспейса, внутри .git/ или через ссылку, ведущую наружу.Используйте относительный путь.
FS_ERRORЛюбая другая проблема с файлом; data.conflict, если не совпал ifMtimeMs.
NOT_VISIBLEНужно, чтобы карточка была на экране: диалоги, ссылки, полёт камеры, запросы разрешений, промпты агенту в опасном режиме.Повторите, когда card.visibility === 'visible'.
USER_CANCELLEDПользователь отказался (подтверждение, промпт агенту в опасном режиме) или вызов отменён.
UNAVAILABLEЦель не запущена, воркспейс не открыт, карточка усыплена или соединение закрыто.
PROTOCOL_MISMATCHКарточка сделана под более новый протокол, чем знает приложение.Пользователь обновляет NeuroSquad.
NOT_READYВызов сделан до завершения рукопожатия.Дождитесь connect().
INTERNALОшибка в приложении.Сообщите о ней, приложив журнал карточки.

Лимиты

Все лимиты есть в card.limits (константа LIMITS из SDK). Дешёвые SDK проверяет до отправки; приложение соблюдает все.

ОбластьЛимит
Сообщениядо 1 МБ каждое (запросы fs.write и net.fetch и ответы fs.read, fs.list, net.fetch — до 12 МБ); до 64 вызовов одновременно (сверх этого SDK ставит их в очередь); 200 вызовов/с, всплески до 400; значения не глубже 64 уровней и не больше 200 000 узлов
Пакетархив до 50 МБ; распакованный до 100 МБ; до 5 000 файлов; каждый до 20 МБ; пути до 240 символов и 20 уровней; манифест до 256 КБ; иконка до 128 КБ
Манифестдо 40 настроек; до 16 входов и 16 выходов; до 32 инструментов; до 32 сетевых хостов; схемы до 500 узлов и 16 уровней, enum до 256 вариантов и 16 КБ, const до 4 КБ
Хранилищеключ до 256 символов; значение до 1 МБ; до 10 000 ключей; 5 МБ на карточку, 20 МБ на пакет
Сетьтело до 5 МБ; ответ до 10 МБ; 6 одновременно; 120 в минуту; до 5 редиректов; тайм-аут 30 с (максимум 120 с), включая тело; до 4 потоков, каждый закрывается после 5 минут тишины или 256 МБ
Файлычтение и запись до 10 МБ; список до 5 000 записей; до 20 наблюдателей
Агентыпромпт до 20 000 символов, 6 в минуту на карточку (метод и порт вместе), до 10 в очереди на агента; команда до 20 000 символов; 30 команд в минуту на карточку (run и порт терминала вместе, тайм-аут до 120 с), write 60 в минуту; экран до 500 строк; вывод доставляется каждые 100 мс или 64 КБ
Инструментырезультат до 1 МБ; тайм-аут 30 с (максимум 120 с); прогресс 4 раза в секунду
Порты20 сообщений/с на выход; сохраняемое значение до 256 КБ; тайм-аут запроса 30 с (максимум 120 с)
Интерфейс карточкизаголовок до 120 (30 в минуту); статус до 80, статус/бейдж/обзор — по 120 в минуту; строки обзора до 160; тост до 280 (один в 2 с); текст подтверждения до 1 000 (10 в минуту); до 12 пунктов меню (30 изменений в минуту); settings.set 60 в минуту; tools.setEnabled 30 в минуту; usage.summary 6 в минуту; внимание раз в 10 с; полёт камеры раз в 5 с; изменение размера раз в 500 мс; до 4 созданных карточек; буфер обмена раз в секунду, до 1 МБ
Журналстрока до 2 000 символов; 50 строк в секунду
Страницыво всём приложении работает до 24 страниц карточек; из них в фоне — до 8; усыпление через 60 с скрытности, на сохранение — 1 с; пульс каждые 5 с, «не отвечает» через 15 с; готовность — в течение 10 с после запуска