# Errors

> Every status code and error body the developer API returns, with the exact messages, what each means and how to fix it.

When a request fails, the API answers with a `4xx` or `5xx` status and a JSON body with three fields:

```json
{
  "error": "tool_error",
  "message": "Unknown Zendesk account \"desk-2\". Call list_accounts to see valid ids.",
  "docs": "https://plugsight.app/developers"
}
```

| Field     | What it is                                               |
| --------- | -------------------------------------------------------- |
| `error`   | A short code you can check in your code.                 |
| `message` | What went wrong, in plain words, and usually what to do. |
| `docs`    | A link to the developer documentation.                   |

## All errors at a glance

| Status | `error`         | What happened                                                                                             | What to do                                      |
| ------ | --------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| 400    | `tool_error`    | The tool couldn't run: a wrong or missing argument, a change that isn't allowed, or the provider said no. | Read `message`: it says what to fix.            |
| 400    | `bad_json`      | The request body isn't valid JSON, so nothing ran.                                                        | Send a JSON object as the body (`{}` for no arguments). |
| 401    | `unauthorized`  | The key is missing, mistyped, replaced or revoked, or the person who made it has left the team or is now a Member.                                                        | Check the header, or create a new key. |
| 403    | `plan_required` | The account isn't on Pro or Agency.                                                                       | Upgrade under **Billing** in the app.           |
| 404    | `unknown_tool`  | The MCP server has no tool by that name, often because the connection it needs isn't in the MCP server.   | `GET /v1/tools` lists what it has.              |
| 404    | `not_found`     | The address isn't an API endpoint.                                                                        | Use `GET /v1/tools` or `POST /v1/tools/<name>`. |
| 429    | `rate_limited`  | Over 120 requests in a minute for this MCP server.                                                        | Wait the `Retry-After` seconds, then retry.     |
| 500    | `server_error`  | Something broke on Plugsight's side.                                                                      | Retry. If it keeps happening, contact support.  |

## 400 tool_error

**What it means:** the request reached the tool, but the tool couldn't do what you asked. The `message` is the tool's own explanation. The most common ones:

| Message starts with                                                                                                           | What to do                                                                                                 |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Unknown account "…"` or `Unknown Zendesk account "…"`                                                                        | Use an `id` from `list_accounts`.                                                                          |
| `This MCP has 2 … connections; pass account (one of: …)`                                                                      | Add the `account` argument with one of the ids listed.                                                     |
| `Not sent:`, `Not posted:`, `Not updated:`, `Not applied:`, `Not created:`, `Not booked:`, `Not changed:` or `Not cancelled:` | Add `"confirm": true` to the arguments, once you've decided to go ahead.                                   |
| `The "…" MCP is set to drafts only` or `The "…" MCP is read-only`                                                             | Tick **Allow changes** on the MCP server's page.                                                           |
| `Sending is off for "…"` or `Changes are off for "…"`                                                                         | Turn on the account's switch under **Write access** on **Connections**.                                    |
| `All write actions are paused` or `… are paused (Permissions page)`                                                           | Click **Resume** on the **Permissions** page.                                                              |
| `Daily limit reached`                                                                                                         | Wait for the 24-hour window to free up, or raise the limit under **Daily email limit** on **Permissions**. |
| `… no longer accepts this connection's sign-in` or `… rejected …`                                                             | Reconnect the account on **Connections**.                                                                  |
| `… is limiting requests right now`                                                                                            | The provider asked to slow down. Wait a minute, then try again.                                            |

The [Troubleshooting](https://docs.plugsight.app/troubleshooting.md) section explains each of these messages in full, including [why changes are refused](https://docs.plugsight.app/troubleshooting/ai-cant-send-or-change.md) and [reconnecting accounts](https://docs.plugsight.app/troubleshooting/reconnect-needed.md).

Arguments that don't match the tool's `input_schema` (a missing required argument, or the wrong type) also return `400 tool_error`, with a message naming the argument.

## 401 unauthorized

### Send your MCP server's API key as: Authorization: Bearer \<key>.

**What it means:** the request had no `Authorization` header, or it didn't start with `Bearer` followed by a key.

**How to fix it:** send the header exactly as `Authorization: Bearer mcpk_…`, with one space after `Bearer`.

### That API key isn't valid. Create a new one on the MCP server's page in Plugsight.

**What it means:** the key is mistyped, was replaced with **Regenerate key**, was turned off with **Revoke key**, its MCP server was deleted, or the person who made it has left the team, been removed, had their account deleted, or become a Member (only Owners and Admins can have working keys).

**How to fix it:** check you copied the whole key. If it's been replaced or revoked, open the MCP server's page and click **Create API key** (or **Regenerate key**), then update the key wherever you use it. See [Authentication](https://docs.plugsight.app/developers/authentication.md).

## 403 plan_required

### The developer API is on the Pro and Agency plans. Upgrade at https://app.plugsight.app/app/billing.

**What it means:** the key is valid, but the Plugsight account it belongs to is on the Free plan.

**How to fix it:** upgrade to Pro or Agency under **Billing**. If your paid plan ended or a payment failed and the account moved to Free, the API stops working until you upgrade again.

## 404 unknown_tool

### This MCP server has no tool "…". GET /v1/tools lists the ones it has.

**What it means:** the name is mistyped, or the tool belongs to a kind of connection the MCP server doesn't include. For example, `zendesk_search_tickets` only exists when the MCP server has a Zendesk connection, and marketing tools only exist on Pro and Agency.

**How to fix it:**

1. Call `GET /v1/tools` and check the exact name.
2. If the tool is missing, open the MCP server's page in the app, click **Edit configuration**, and add the account it needs (or choose **All accounts**).

## 404 not_found

### Unknown endpoint. Use GET /v1/tools or POST /v1/tools/\<name>.

**What it means:** the path isn't one of the API's two endpoints, or it used the wrong method (for example `GET` to run a tool).

**How to fix it:** list tools with `GET /v1/tools`, and run one with `POST /v1/tools/<name>`.

## 429 rate_limited

### Too many requests: up to 120 a minute per MCP server. Try again shortly.

**What it means:** this MCP server's key made more than 120 requests in a minute. The answer has a `Retry-After: 60` header.

**How to fix it:**

1. Wait the number of seconds in `Retry-After`, then retry.
2. Cache results on your side, especially data you show on a website.
3. If you need more, split the work across a second MCP server with its own key.

## 500 server_error

### Something went wrong on our side. Try again; if it keeps happening, contact support.

**What it means:** an unexpected failure inside Plugsight.

**How to fix it:** retry the request. If it keeps happening, email info@plugsight.app with the tool name, the `error` and `message` you got, and the time of the request.

## Related articles

- [Calling tools](https://docs.plugsight.app/developers/calling-tools.md)
- [Authentication](https://docs.plugsight.app/developers/authentication.md)
- [Troubleshooting](https://docs.plugsight.app/troubleshooting.md)

---

Web version: https://docs.plugsight.app/developers/errors
