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:
{
"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. |
| 401 | unauthorized |
The key is missing, mistyped, replaced or revoked. | 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 section explains each of these messages in full, including why changes are refused and reconnecting accounts.
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, or its MCP server was deleted.
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.
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:
- Call
GET /v1/toolsand check the exact name. - 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:
- Wait the number of seconds in
Retry-After, then retry. - Cache results on your side, especially data you show on a website.
- 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.