MCP limits and error codes

The BLACKBOX MCP server (https://api.app.blackbox.md/mcp) limits the number of calls and, when something goes wrong, replies with a short message in English or with an error code. Here you will find the limits, the HTTP responses you may get when connecting (401, 404, 421) and the tool error codes, with what to do in each case. You create and revoke tokens on blackbox.md, in “Contul meu” (My account) → “Token-uri API” (API tokens) (blackbox.md/account/api-tokens).

Available to: any blackbox.md customer who connects an AI assistant with an API token.

The blackbox.md website is available in Romanian and Russian; this article quotes the Romanian labels with their English meaning.

The general limit: 120 calls per minute

An account can make at most 120 tool calls in any 60-second window. The limit applies to the account, not to the token: all your tokens and all your AI clients share it.
Over the limit, the tool returns the rate_limited error. This is not an HTTP 429 error: the connection stays active, and only the call is refused.
The count covers the calls made in the last 60 seconds, including refused ones. If the assistant keeps retrying in a loop, it stays blocked. Stop the calls and wait a full minute.
whoami and list_vm_plans don't count toward the limit.
MCP limits are separate from the limits of the panel buttons and the blackbox.md pages. You will find those in The “Too many attempts” message and usage limits.

Limits for each tool

In addition to the general limit, most tools also have a limit of their own, also per account. Going over it gives the same error, rate_limited. What each tool does: List of MCP tools.

Tool	Limit
`create_order`	20 per hour, including price quotes (`confirm=false`)
`pay_order`	10 per minute
`cancel_order`	5 in 5 minutes, including previews
`resize_server`	3 in 10 minutes, including previews
`run_server_command`	30 per minute
`reveal_server_credentials`	20 per minute
`reset_server_password`	3 in 5 minutes
`power_server`	6 per minute
`get_server_ssh_access`	10 in 5 minutes
`add_server_ssh_key`, `remove_server_ssh_key`	10 in 5 minutes each
`set_server_password_auth`	5 in 5 minutes
`list_server_ssh_keys`, `list_ssh_keys`	30 per minute each
`add_ssh_key`	10 per hour
`delete_ssh_key`	20 per hour
`list_servers`, `get_server`, `get_balance`	60 per minute each
`list_transactions`, `list_orders`, `list_invoices`	30 per minute each
`get_server_resize_options`	the general limit only
`whoami`, `list_vm_plans`	no limit

Warning Price quotes and previews use up the limit just like the actions themselves. Three upgrade previews use up resize_server for 10 minutes. Ask the assistant for a single preview, check it, then confirm.

Connection errors (HTTP)

These errors appear before the assistant can use any tool, and the AI client shows the connection as failed. The exact reason appears in the client's log, or when you test with MCP Inspector or with an HTTP request: see Using MCP from code (AI APIs and HTTP).

401: token missing or not recognized

For any problem with the token, the server replies with HTTP 401 and the body {"error":"invalid_token","error_description":"…"}. The error_description field shows the reason:

`error_description`	Cause	What to do
`authorization header missing`	The request has no `Authorization` header and no alternative header with the token.	Add `Authorization: Bearer bbx_pat_…`. In the Claude app, check the `x-api-key` header: the name must be spelled exactly, and the value must start with `bbx_pat_`. See Connecting in the Claude app (custom connector).
`unsupported authorization scheme (expected: Bearer <token>)`	The `Authorization` header doesn't start with `Bearer` followed by a space: the word `Bearer` is missing, there is a different word in front, or nothing follows `Bearer`.	Write `Bearer`, a space, then the token. If you keep the token in an environment variable, check that the variable isn't empty.
`bearer token is empty`	No token follows `Bearer` .	Check that the token (or the environment variable that holds it) isn't empty.
`token not recognised (expected a bbx_pat_ personal access token)`	The text after `Bearer` doesn't start with `bbx_pat_`: it is a different key, it has extra quotation marks, or there are two spaces after `Bearer`.	Copy the token exactly, without quotation marks, with a single space after `Bearer`.
`token not recognised (revoked, expired, or unknown)`	The token has the right format but isn't valid: it was revoked, it was created before the last change of the account password, the account was deleted, or the token was copied incompletely.	Create a new token and replace the old one in the client (see the section about the password below).

Important There must be exactly one space between Bearer and the token. With two spaces, the token reaches the server with a space in front of it and is rejected. The word Bearer can be written in uppercase or lowercase.

Authorization: Bearer bbx_pat_…

404 and 421

Response	Cause	What to do
HTTP 404	The address has a path other than `/mcp`, or the MCP service is temporarily unavailable.	Use exactly `https://api.app.blackbox.md/mcp`. If the address is correct, try again later, and if the error persists, write to us: How to contact BLACKBOX support.
HTTP 421 (Misdirected Request)	The request has a host name other than `api.app.blackbox.md`, for example because a proxy changed the `Host` header.	Use the name `api.app.blackbox.md`, exactly as in the address above.

Tool error codes

When a tool fails, the assistant receives a short code, sometimes followed by details after a “:”, for example missing_scope: this token does not have 'orders:write'. The connection stays active. If the assistant only summarizes the error, ask it for the exact text.

Common errors

Code	What it means	What to do
`rate_limited`	The general limit or the tool's own limit was exceeded.	Stop calling that tool for as long as the limit's window lasts (one minute, 5 minutes, 10 minutes or one hour). Don't retry in a loop.
`missing_scope`	The token doesn't have the required permission; the message names it.	Create a new token with that permission, put it in the client and revoke the old one. You can't change the permissions of an existing token. See Token permissions (scopes).
`not_found`	The ID doesn't exist or belongs to another account; the two cases look the same on purpose. The same code appears for an action on a server you can only view (in the panel, it has the “Managed” badge).	Ask the assistant to take the ID from `list_servers`, `list_orders` or `list_ssh_keys`. For “Managed” servers, write to us.
`invalid_server_id`, `invalid_order_id`, `invalid_key_id`	The ID has the wrong format: for example, the assistant sent the server's name or IP address.	Ask it to use the `id` field from `list_servers`, `list_orders` or `list_ssh_keys`.
`internal_error`	An unexpected error on the BLACKBOX side.	Try again once. If it happens again, write to us with the time and the name of the tool.
A message saying that the infrastructure service is temporarily unavailable	During an upgrade or the cancellation of an order with a server, the infrastructure did not respond. Nothing was changed and nothing was charged.	Try again in a few minutes. If it persists, write to us.

Servers and commands on the server

Code	What it means	What to do
`invalid_action`	`power_server` received an unknown action.	The valid actions are `reboot`, `stop` and `start`.
`no_instance_id`	The server is not a virtual machine that BLACKBOX can start or stop automatically (for example, a server registered manually or an older server that your account has access to). On some of these servers, only `reboot` works.	For other actions, write to us.
`power_action_failed`	The infrastructure did not carry out the start, stop or reboot command.	Check the state with `get_server` (`power_state`) and try again after a minute. If it persists, write to us.
`reset_failed`	The password could not be changed, usually because the server is stopped or not responding. The old password remains valid.	Start the server, wait for it to boot and try again (at most 3 resets in 5 minutes).
`ssh_connection_failed`	The BLACKBOX management connection did not reach the server: the server is stopped or still booting, SSH is not responding, root can no longer sign in with a key, or the “Management key (blackbox.md)” was deleted.	Check that the server is running, wait 30–60 seconds after a reboot and try again once. If it persists, see Running commands on the server through AI or write to us.
`invalid_command`	The command is empty or longer than 8,192 characters.	Check that the call contains a command. Split a command that is too long into several calls.

Orders, payments, cancellations and upgrades

Code	What it means	What to do
`unsupported_os`	The requested operating system can't be installed automatically (for example, Windows). The message lists the accepted IDs.	Choose one of `ubuntu-24`, `ubuntu-22`, `ubuntu-20`, `debian-12`, `debian-11`, `centos-9`, `almalinux-9`. Windows is available only on request, through support.
`configurator_retired`	The custom configuration no longer exists: it has been replaced by fixed plans.	Ask the assistant for `list_vm_plans` and choose a plan.
`plan_retired`	The requested plan has been retired. The message suggests the closest `vm-…` plan.	Check the price of the suggested plan with `list_vm_plans` and order that one.
`plan_unavailable`	The plan's hardware configuration is temporarily unavailable. The order was not created.	Choose a similar plan from `list_vm_plans` or try again later.
`price_changed`	The amount sent to `pay_order` is not the current price; the message shows the correct price. Nothing was charged.	Check the new price and confirm the payment with the correct amount.
`insufficient_balance`	Your balance doesn't cover the payment or the upgrade. For an upgrade, the error already appears at the preview. Nothing was charged.	Top up your balance on blackbox.md: “Contul meu” (My account) → “Sold” (Balance) → “Alimentează soldul” (Top up balance). The assistant can't do this. See Topping up your balance.
`not_payable`	The order no longer has the “Nou” (New) status. The message shows the status in English: `in_progress` = “În lucru” (In progress), `done` = “Finalizat” (Completed), `cancelled` = “Anulat” (Canceled).	Check the order in “Contul meu” → “Comenzi” (Orders). Don't pay for it again.
`already_settled`	The order was paid in the meantime, for example by card. Nothing was charged to your balance.	Check the order in “Contul meu” → “Comenzi” or ask for `list_orders`.
`provisioning_in_progress`	The order's server is being created right now, so the order can't be canceled.	Wait a few minutes, then ask for a new cancellation preview.
`not_cancellable`	The order has the “Finalizat” or “Anulat” status and can no longer be canceled.	Check the status with `list_orders`. For a completed order, write to us.
`state_changed`	The order changed between the preview and the confirmation.	Ask for a new preview and confirm that one.
`target_not_a_candidate`	The plan chosen for the upgrade is not among the allowed options: only larger plans of the same family.	Ask the assistant to run `get_server_resize_options` again and choose exactly one of the options.
`job_active`	An upgrade of this server is already in progress.	Wait a few minutes for it to finish. Don't start a second one.
`not_upgradeable_plan`	The server's plan (“VPS hosting” with a control panel, or a dedicated server) can't be upgraded automatically.	Write to us for a larger configuration.
`vm_not_resizable`	The server is in a transition state, for example it is being created or is already being upgraded.	Try again in a few minutes.

How price quotes, payment and cancellation work through AI: Orders, payments, cancellations and upgrades via AI.

SSH keys

Code	What it means	What to do
`management_key_protected`	There was an attempt to delete the “Management key (blackbox.md)” from the server. It can't be deleted: the panel and the AI assistant work through it.	No action is needed. See BLACKBOX keys on your server.
`last_key_on_key_only_server`	The deletion would remove your last key from a “Key-only” server, and you would lose SSH access.	First add another key or turn on password login, then delete the key.
`no_customer_key_installed`	Password login can't be turned off: none of your keys is installed on the server.	First install your key on the server (`add_server_ssh_key`), then try again.
`operation_in_progress`	A change to the keys or to password login is already running on the same server.	Wait a minute and try again.
`private_key_submitted`	A private key was sent instead of the public one. It was not saved.	Send the contents of the `.pub` file. The private key has reached your conversation with the assistant: consider it exposed and generate a new key pair (Generating an SSH key (Windows, macOS, Linux)).
`duplicate_key`	The key already exists in your account.	Use the existing key (`list_ssh_keys`).
`too_many_keys`	The account already has 20 keys, the maximum.	Delete a key you no longer use (`delete_ssh_key`), then add the new one.
`unsupported_key_type`, `key_too_weak`, `invalid_public_key`	The text is not a valid OpenSSH public key, has an unsupported type, or is an RSA key under 2048 bits.	Use an `ssh-ed25519` key, an RSA key of at least 2048 bits, or an ECDSA key.

Security Don't send your token to support and don't leave it in screenshots. To look into a problem, we only need the time, the name of the tool and the error message. If a token has ended up somewhere public, revoke it immediately.

The token stops working after a password change

When you change your blackbox.md account password, all tokens created before the change stop working, and the AI client receives token not recognised (revoked, expired, or unknown). The old tokens stay in the list with no marker of any kind.

On blackbox.md, open “Contul meu” (My account) → “Token-uri API” (API tokens).
Create a new token with the same permissions and copy it. Steps: API tokens: creating, copying and revoking.
Replace the old token in the AI client and reconnect the client.
Ask the assistant to call whoami: the response confirms the account and shows which permissions are missing.
Revoke the old tokens with “Revocă” (Revoke).

Signing out of blackbox.md does not stop your tokens from working.

Frequently asked questions

My token worked yesterday, but today I get 401. Why? Possible causes: the token was revoked, or the account password was changed in the meantime. Read error_description in the response and follow its row in the 401 table.

The assistant says a tool doesn't exist. Why? The AI client sees only the tools the token has permission for. Create a new token with the permission you need.

Do the limits reset at a fixed time? No. The count covers the calls in the latest window (one minute, 5 minutes, 10 minutes or one hour, depending on the limit). Once you stop the calls, access comes back on its own.

Do the panel buttons use up the MCP limits? No. The panel and MCP have separate limits, even for the same actions.