Лимиты и коды ошибок MCP
Лимиты вызовов, сообщения 401 и коды ошибок инструментов с решением для каждого.
На этой странице
Сервер MCP BLACKBOX (https://api.app.blackbox.md/mcp) ограничивает число вызовов, а при сбое отвечает коротким сообщением на английском или кодом ошибки. Здесь собраны лимиты, HTTP-ответы при подключении (401, 404, 421) и коды ошибок инструментов — и что делать в каждом случае. Токены создаются и отзываются на blackbox.md: «Личный кабинет» → «API-токены» (blackbox.md/ru/account/api-tokens).
Доступно: любому клиенту blackbox.md, который подключает AI-ассистента с API-токеном.
Общий лимит: 120 вызовов в минуту
- Один аккаунт может сделать не больше 120 вызовов инструментов за любые 60 секунд. Лимит действует на аккаунт, а не на токен: все ваши токены и AI-клиенты расходуют его вместе.
- При превышении инструмент возвращает ошибку
rate_limited. Это не HTTP 429: соединение остаётся рабочим, отклоняется только сам вызов. - Считаются вызовы за последние 60 секунд, включая отклонённые. Если ассистент повторяет запросы в цикле, блокировка не снимается. Прекратите вызовы и подождите целую минуту.
whoamiиlist_vm_plansв лимит не входят.- Лимиты MCP не связаны с лимитами кнопок в панели и страниц blackbox.md. Они описаны в статье Сообщение «Слишком много попыток» и лимиты использования.
Лимиты отдельных инструментов
Кроме общего лимита, у большинства инструментов есть и собственный, тоже на аккаунт. При превышении — та же ошибка rate_limited. Что делает каждый инструмент: Список инструментов MCP.
| Инструмент | Лимит |
|---|---|
create_order |
20 в час, включая расчёты цены (confirm=false) |
pay_order |
10 в минуту |
cancel_order |
5 за 5 минут, включая предпросмотры |
resize_server |
3 за 10 минут, включая предпросмотры |
run_server_command |
30 в минуту |
reveal_server_credentials |
20 в минуту |
reset_server_password |
3 за 5 минут |
power_server |
6 в минуту |
get_server_ssh_access |
10 за 5 минут |
add_server_ssh_key, remove_server_ssh_key |
по 10 за 5 минут |
set_server_password_auth |
5 за 5 минут |
list_server_ssh_keys, list_ssh_keys |
по 30 в минуту |
add_ssh_key |
10 в час |
delete_ssh_key |
20 в час |
list_servers, get_server, get_balance |
по 60 в минуту |
list_transactions, list_orders, list_invoices |
по 30 в минуту |
get_server_resize_options |
только общий лимит |
whoami, list_vm_plans |
без лимита |
Внимание Расчёты цены и предпросмотры расходуют лимит так же, как сами действия. Три предпросмотра апгрейда исчерпывают
resize_serverна 10 минут. Попросите ассистента сделать один предпросмотр, проверьте его и только потом подтверждайте.
Ошибки при подключении (HTTP)
Эти ошибки возникают до того, как ассистент сможет вызвать хоть один инструмент, — AI-клиент показывает, что подключиться не удалось. Точную причину можно увидеть в журнале клиента либо при проверке через MCP Inspector или HTTP-запросом: см. Использование MCP из кода (AI API и HTTP).
401: токен не передан или не распознан
При любой проблеме с токеном сервер отвечает HTTP 401 с телом {"error":"invalid_token","error_description":"…"}. Причина указана в поле error_description:
error_description |
Причина | Что делать |
|---|---|---|
authorization header missing |
В запросе нет заголовка Authorization и нет альтернативного заголовка с токеном. |
Добавьте Authorization: Bearer bbx_pat_…. В приложении Claude проверьте заголовок x-api-key: имя должно быть написано точно, значение — начинаться с bbx_pat_. См. Подключение в приложении Claude (пользовательский коннектор). |
unsupported authorization scheme (expected: Bearer <token>) |
Заголовок Authorization не начинается с Bearer и пробела: слова Bearer нет, перед токеном стоит другое слово или после Bearer ничего нет. |
Напишите Bearer, пробел и токен. Если токен хранится в переменной окружения, убедитесь, что она не пустая. |
bearer token is empty |
После Bearer нет токена. |
Убедитесь, что токен (или переменная окружения с ним) не пустой. |
token not recognised (expected a bbx_pat_ personal access token) |
Текст после Bearer не начинается с bbx_pat_: это другой ключ, лишние кавычки или два пробела после Bearer. |
Скопируйте токен точно, без кавычек, с одним пробелом после Bearer. |
token not recognised (revoked, expired, or unknown) |
Формат токена верный, но токен недействителен: его отозвали, он создан до последней смены пароля аккаунта, аккаунт удалён или токен скопирован не полностью. | Создайте новый токен и замените его в клиенте (см. раздел о смене пароля ниже). |
Важно Между
Bearerи токеном должен быть ровно один пробел. С двумя пробелами токен приходит на сервер с пробелом в начале и отклоняется. СловоBearerможно писать в любом регистре.
Authorization: Bearer bbx_pat_…404 и 421
| Ответ | Причина | Что делать |
|---|---|---|
| HTTP 404 | Путь в адресе не /mcp либо сервис MCP временно недоступен. |
Используйте адрес точно: https://api.app.blackbox.md/mcp. Если адрес верный, повторите позже, а если ошибка не исчезает, напишите нам: Как связаться с поддержкой BLACKBOX. |
| HTTP 421 (Misdirected Request) | В запросе указано другое имя хоста, а не api.app.blackbox.md — например, его подменил прокси в заголовке Host. |
Используйте имя api.app.blackbox.md, как в адресе выше. |
Коды ошибок инструментов
Если инструмент не сработал, ассистент получает короткий код, иногда с подробностями после «:», например missing_scope: this token does not have 'orders:write'. Соединение при этом не обрывается. Если ассистент лишь пересказывает ошибку, попросите его привести точный текст.
Общие ошибки
| Код | Что означает | Что делать |
|---|---|---|
rate_limited |
Превышен общий лимит или лимит инструмента. | Не вызывайте этот инструмент, пока не пройдёт окно лимита (минута, 5 минут, 10 минут или час). Не повторяйте вызовы в цикле. |
missing_scope |
У токена нет нужного разрешения; оно названо в сообщении. | Создайте новый токен с этим разрешением, пропишите его в клиенте, а старый отзовите. Разрешения существующего токена изменить нельзя. См. Разрешения токенов (scopes). |
not_found |
Такого ID нет или он принадлежит другому аккаунту; оба случая намеренно выглядят одинаково. Тот же код приходит при действии с сервером, который вам доступен только для просмотра (в панели у него метка «Обслуживается»). | Попросите ассистента взять ID из list_servers, list_orders или list_ssh_keys. По серверам с меткой «Обслуживается» напишите нам. |
invalid_server_id, invalid_order_id, invalid_key_id |
ID в неверном формате: например, ассистент передал имя или IP сервера. | Попросите его использовать поле id из list_servers, list_orders или list_ssh_keys. |
internal_error |
Непредвиденная ошибка на стороне BLACKBOX. | Повторите один раз. Если ошибка повторяется, напишите нам время и название инструмента. |
| Сообщение о том, что инфраструктурный сервис временно недоступен | При апгрейде или отмене заказа с сервером инфраструктура не ответила. Ничего не изменилось, деньги не списаны. | Повторите через несколько минут. Если не помогает, напишите нам. |
Серверы и команды на сервере
| Код | Что означает | Что делать |
|---|---|---|
invalid_action |
power_server получил неизвестное действие. |
Допустимые действия: reboot, stop и start. |
no_instance_id |
Сервер не является виртуальной машиной, которую BLACKBOX может автоматически включать и выключать (например, сервер, добавленный вручную, или старый сервер, к которому у вашего аккаунта есть доступ). На некоторых таких серверах работает только reboot. |
Для других действий напишите нам. |
power_action_failed |
Инфраструктура не выполнила команду включения, выключения или перезагрузки. | Проверьте состояние через get_server (power_state) и повторите через минуту. Если не помогает, напишите нам. |
reset_failed |
Пароль не удалось сменить — обычно потому, что сервер выключен или не отвечает. Старый пароль продолжает действовать. | Включите сервер, дождитесь загрузки и повторите (не больше 3 сбросов за 5 минут). |
ssh_connection_failed |
Служебное подключение BLACKBOX не дошло до сервера: сервер выключен или ещё загружается, SSH не отвечает, root больше не может входить по ключу или удалён «Ключ управления (blackbox.md)». | Убедитесь, что сервер работает, после перезагрузки подождите 30–60 секунд и повторите один раз. Если не помогает, см. Выполнение команд на сервере через AI или напишите нам. |
invalid_command |
Команда пустая или длиннее 8192 символов. | Проверьте, что в вызове есть команда. Слишком длинную команду разбейте на несколько вызовов. |
Заказы, оплата, отмена и апгрейд
| Код | Что означает | Что делать |
|---|---|---|
unsupported_os |
Выбранную ОС нельзя установить автоматически (например, Windows). В сообщении перечислены допустимые ID. | Выберите один из вариантов: ubuntu-24, ubuntu-22, ubuntu-20, debian-12, debian-11, centos-9, almalinux-9. Windows — только по запросу через поддержку. |
configurator_retired |
Индивидуальной конфигурации больше нет: её заменили фиксированные тарифы. | Попросите ассистента вызвать list_vm_plans и выберите тариф. |
plan_retired |
Тариф выведен из продажи. В сообщении предложен ближайший тариф vm-…. |
Проверьте цену предложенного тарифа через list_vm_plans и закажите его. |
plan_unavailable |
Оборудование для этого тарифа временно недоступно. Заказ не создан. | Выберите близкий тариф из list_vm_plans или повторите позже. |
price_changed |
Сумма, переданная в pay_order, не совпадает с текущей ценой; верная цена указана в сообщении. Деньги не списаны. |
Проверьте новую цену и подтвердите оплату с правильной суммой. |
insufficient_balance |
Баланса не хватает на оплату или апгрейд. При апгрейде ошибка появляется уже на предпросмотре. Деньги не списаны. | Пополните баланс на blackbox.md: «Личный кабинет» → «Баланс» → «Пополнить баланс». Ассистент этого сделать не может. См. Пополнение баланса. |
not_payable |
Заказ уже не в статусе «Новый». Статус в сообщении указан по-английски: in_progress — «В работе», done — «Завершён», cancelled — «Отменён». |
Проверьте заказ в разделе «Личный кабинет» → «Заказы». Не оплачивайте его повторно. |
already_settled |
Заказ тем временем уже оплачен — например, картой. С баланса ничего не списано. | Проверьте заказ в разделе «Личный кабинет» → «Заказы» или попросите вызвать list_orders. |
provisioning_in_progress |
Сервер по заказу как раз создаётся, поэтому отменить заказ сейчас нельзя. | Подождите несколько минут и запросите новый предпросмотр отмены. |
not_cancellable |
У заказа статус «Завершён» или «Отменён», отменить его уже нельзя. | Проверьте статус через list_orders. По завершённому заказу напишите нам. |
state_changed |
Заказ изменился между предпросмотром и подтверждением. | Запросите новый предпросмотр и подтвердите уже его. |
target_not_a_candidate |
Выбранный для апгрейда тариф не входит в допустимые варианты — только более крупные тарифы того же семейства. | Попросите ассистента заново вызвать get_server_resize_options и выбрать ровно один из предложенных вариантов. |
job_active |
Апгрейд этого сервера уже выполняется. | Подождите несколько минут, пока он закончится. Второй не запускайте. |
not_upgradeable_plan |
Тариф сервера («VPS hosting» с панелью или выделенный сервер) нельзя увеличить автоматически. | Напишите нам, чтобы подобрать конфигурацию больше. |
vm_not_resizable |
Сервер в переходном состоянии — например, ещё создаётся или уже увеличивается. | Повторите через несколько минут. |
Как через AI работают расчёт цены, оплата и отмена: Заказы, оплата, отмена и апгрейд через AI.
SSH-ключи
| Код | Что означает | Что делать |
|---|---|---|
management_key_protected |
Была попытка удалить с сервера «Ключ управления (blackbox.md)». Его удалить нельзя: через него работают панель и AI-ассистент. | Ничего делать не нужно. См. Ключи BLACKBOX на вашем сервере. |
last_key_on_key_only_server |
Удаление сняло бы ваш последний ключ с сервера «Только ключ», и вы потеряли бы доступ по SSH. | Сначала добавьте другой ключ или включите вход по паролю, затем удалите этот ключ. |
no_customer_key_installed |
Вход по паролю нельзя отключить: на сервере не установлено ни одного вашего ключа. | Сначала установите свой ключ на сервер (add_server_ssh_key), затем повторите. |
operation_in_progress |
На этом сервере уже идёт другое изменение ключей или входа по паролю. | Подождите минуту и повторите. |
private_key_submitted |
Вместо публичного ключа передан приватный. Он не сохранён. | Передайте содержимое файла .pub. Приватный ключ уже попал в переписку с ассистентом: считайте его скомпрометированным и создайте новую пару (Создание SSH-ключа (Windows, macOS, Linux)). |
duplicate_key |
Такой ключ уже есть в вашем аккаунте. | Используйте существующий ключ (list_ssh_keys). |
too_many_keys |
В аккаунте уже 20 ключей — это максимум. | Удалите ключ, которым больше не пользуетесь (delete_ssh_key), и добавьте новый. |
unsupported_key_type, key_too_weak, invalid_public_key |
Текст не является корректным публичным ключом OpenSSH, тип ключа не поддерживается или это ключ RSA короче 2048 бит. | Используйте ключ ssh-ed25519, RSA не короче 2048 бит или ECDSA. |
Безопасность Не отправляйте токен в поддержку и не оставляйте его на скриншотах. Чтобы разобраться с проблемой, нам достаточно времени, названия инструмента и текста ошибки. Если токен оказался в открытом доступе, сразу отзовите его.
Токен перестал работать после смены пароля
Когда вы меняете пароль аккаунта blackbox.md, перестают работать все токены, созданные до смены, и AI-клиент получает token not recognised (revoked, expired, or unknown). В списке старые токены остаются без какой-либо пометки.
- На blackbox.md откройте «Личный кабинет» → «API-токены».
- Создайте новый токен с теми же разрешениями и скопируйте его. Подробно: API-токены: создание, копирование и отзыв.
- Замените старый токен в AI-клиенте и переподключите клиент.
- Попросите ассистента вызвать
whoami: в ответе будет ваш аккаунт и список недостающих разрешений. - Отзовите старые токены кнопкой «Отозвать».
Выход из аккаунта на blackbox.md на токены не влияет.
Частые вопросы
Вчера токен работал, а сегодня приходит 401. Почему?
Возможные причины: токен отозвали или за это время сменили пароль аккаунта. Посмотрите error_description в ответе и найдите эту строку в таблице ошибок 401.
Ассистент говорит, что такого инструмента нет. Почему? AI-клиент видит только те инструменты, на которые у токена есть разрешение. Создайте новый токен с нужным разрешением.
Лимиты сбрасываются в определённое время? Нет. Считаются вызовы за последнее окно (минута, 5 минут, 10 минут или час — в зависимости от лимита). Когда вы прекращаете вызовы, доступ восстанавливается сам.
Расходуют ли кнопки в панели лимиты MCP? Нет. У панели и MCP отдельные лимиты, даже для одинаковых действий.