> ## Documentation Index
> Fetch the complete documentation index at: https://codebeans-cb-notifylyst.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Error codes

> Every refusal the connector can return, what caused it, and what fixes it.

Two things worth knowing before you read the tables.

**Every token refusal is a 401 — read the code.** A bad token, a disabled or expired one, the
connector switched off, an uninstalled app and a plan without the connector all come back as
**401**. The code tells them apart, and reconnecting only helps when the fix is a new token.

**Not every non-200 is a fault.** `GET /mcp` answers **405** on purpose. The connector answers each
request and offers no streaming connection; 405 is how a client is told there is none to open.

## What the connector returns

The connector checks in this order and stops at the first problem: token format, token exists,
token active, expiry, the store's **Connector** switch, app still installed, plan, rate limit.

| Status | Code | Meaning | Fix |
| - | - | - | - |
| **401** | — | "Missing or invalid Authorization header. Expected Bearer token." | Send the header `Authorization: Bearer nl_mcp_…`. In Claude, reconnect the connector. |
| **401** | `INVALID_TOKEN_FORMAT` | What was sent isn't a Notifylyst token. | Copy the whole token, starting `nl_mcp_`. |
| **401** | `INVALID_MCP_TOKEN` | The token is unknown — revoked, regenerated, or never existed. | Use the regenerated token, or create a new one. |
| **401** | `MCP_TOKEN_DISABLED` | The token is disabled. | **Enable** it in the **Access tokens** table. |
| **401** | `MCP_TOKEN_EXPIRED` | The token passed its expiry. | Create a new token. An expired token can't be regenerated. |
| **401** | `MCP_DISABLED` | The store's **Connector** switch is off. Every token is refused. | **Turn on** on the **Connector** card. |
| **401** | `SHOP_NOT_INSTALLED` | Notifylyst was uninstalled from that store. | Reinstall the app. |
| **401** | `MCP_PLAN_DISABLED` | Your plan doesn't include **AI MCP Integration**. | Change plan on the app's **Plans** page. |
| **429** | `RATE_LIMIT_EXCEEDED` | More requests a minute than your plan allows. The response includes a Retry-After time. | Wait that long, then ask a narrower question. |
| **405** | — | Something sent `GET /mcp` instead of `POST`. | **Working as designed.** Point uptime monitors at `/healthz`. |
| **500** | — | "Internal server error: Tool execution timed out." The request ran for about 28 seconds. | Narrow the date range or the page size and ask again. |
| **502** | — | "Upstream authorization service unavailable." The connector couldn't reach your Notifylyst app. | Retry shortly; contact support if it persists. |

## Errors that arrive inside an answer

When the connection is fine but the tool can't do what was asked, the answer itself says so, with
an error and a hint:

| What you see | Meaning |
| - | - |
| "Validation failed." | An argument was rejected — a malformed id, a value out of range. The issues are listed with it. Restating the question with the exact product or date usually settles it. |
| "Forbidden: this token is not allowed to use this tool." | The token doesn't allow that tool. Create a new token that includes it — a token's tools can't be edited. |
| "This store is currently disabled." | The store can't be served right now. Contact support. |
| Any other message | A refusal from the app itself, such as a test send to an address that isn't one of your store's own. The message says what to change. |
| An empty result where you expected rows | Almost always the date range or a channel filter, not missing data. Ask which range and filter it used. |

## Confirmation statuses

Tools that change something answer with one of these statuses:

| Status | Meaning |
| - | - |
| `confirmation_required` | The first call — a preview. **Nothing changed.** It carries a summary, details, warnings, a confirmation ticket, and when the ticket expires. The AI should show you the summary and ask. |
| `refused` | The change isn't allowed, with the reason — for example, the setting is already set that way. |
| `confirmation_invalid` | The ticket can't be used. The message says why: "Malformed confirmationId.", "This confirmation has expired (they last 5 minutes).", "The arguments do not match…", or "This confirmation was already used." Ask again to get a fresh preview. |

## On the connect page

These appear on the **Connect to Notifylyst** page in your browser:

| Message starts with | Fix |
| - | - |
| "Paste your Notifylyst MCP token to continue." | The field was empty. Paste the token. |
| "That token has expired." | Create a new token. |
| "That token has been disabled." | **Enable** it, or create a new one. |
| "The MCP integration is switched off for that store." | **Turn on** on the **Connector** card. |
| "That token was not recognised." | Copy it again from the app, or create a new one. |

A few plain pages can also appear if the client's request itself is wrong — "Missing client",
"Unknown application", "Missing redirect" or "Redirect not allowed". Each says "Nothing was shared
and no access was granted. You can close this window." Start the connection again from your client.

## Client-side messages that are not our errors

| Message | What it really is |
| - | - |
| `Failed to reconnect SSE stream` `Maximum reconnection attempts exceeded` | Your client tried to hold a streaming connection open, which the connector does not offer (see the 405 above). Restart the client, and prefer a native config over `mcp-remote` where your client supports one — see [Other AI clients](https://codebeans-cb-notifylyst.mintlify.site/mcp/setup/other-clients.md). |

## Checking a refusal yourself

The health check answers the "is it the token or the client?" question in one command:

```bash theme={"system"}
curl -s https://notifylyst-mcp.cblyst.com/healthz \
  -H "Authorization: Bearer nl_mcp_…"
```

* **200, status `ready`, with the store, allowed tools and expiry** → the token is fine; the
  problem is client-side.
* **401** → the token can't be used. This covers every refusal, including the **Connector** switch
  being off and the plan not including the connector.
* **429** → over the rate limit.

Each check uses one request from your rate limit.

Symptom-first version of this page: [Troubleshooting](https://codebeans-cb-notifylyst.mintlify.site/mcp/troubleshooting.md).


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