> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The HTTP errors the MCP servers return, and how tool problems are reported.

## What is this?

MCP has two layers of errors. **Connection errors** are plain HTTP responses from the server before any tool runs (a missing key, no channel, a plan that doesn't include MCP). **Tool problems** are reported back to the assistant as the result of the tool call, so it can explain them in plain words.

## What can I do here?

* Fix a connection that won't start
* Recognize why a tool is refused or does nothing
* Know what the assistant is telling you

## How to use it

### Connection errors

These use the standard envelope `{ "success": false, "error": "...", "message": "..." }`.

| Status | Meaning |
| - | - |
| `400` | Workspace MCP only: no channel. The `error` is `channel_required` — send the `X-Channel-Id` header (or `?channelId=`). |
| `401` | Missing or invalid API key. |
| `403` | Not allowed: the key's owner lacks the API Access permission, MCP isn't included in the plan or enabled on the installation, the key is used on the wrong platform's address — or, for the Platform MCP, the owner isn't a platform owner or superadmin. |
| `404` | Workspace MCP only: the channel doesn't exist or you can't reach it (always `404`, never `403`, so ids can't be probed). |
| `405` | `GET` or `DELETE` on the server URL. The servers are stateless — clients use `POST`. |
| `429` | Rate limited — wait for `Retry-After` seconds. See [Rate limits](https://docs.xpressbot.org/api-reference/mcp/rate-limits.md). |

### Tool problems

When a tool can't do what was asked, its result carries a plain message the assistant reads out. Common ones:

* **Not found** — an id the assistant used doesn't exist in this channel (for example *AI agent not found in this channel*) or belongs to another platform. Ask it to list first.
* **Nothing to change** — an update was sent with no fields.
* **Refused by a rule** — for example a closed ticket can't be replied to, or an automation that is on must be paused before its flow is replaced.
* **Needs your approval** — Write tools run only after your MCP client's approval step. If nothing happens, check for a pending prompt.
* **Not offered** — a tool you lack permission for never appears in the list at all.

## Troubleshooting / Technical Notes

* **A write never seems to happen.** Your client (Claude Code, Claude Desktop, Cursor, VS Code) asks you to approve each Write tool call — look for a pending approval prompt.
* **The assistant says it can't delete or cancel.** By design: destructive actions are never exposed over MCP and stay in the dashboard.
* **`403` suddenly after it worked.** The plan or the key owner's permissions changed — permissions are re-checked on every call.

## Related docs

* [MCP introduction](https://docs.xpressbot.org/api-reference/mcp/introduction.md)
* [Authentication](https://docs.xpressbot.org/api-reference/mcp/authentication.md)
* [Rate limits](https://docs.xpressbot.org/api-reference/mcp/rate-limits.md)
* [API errors](https://docs.xpressbot.org/api-reference/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.