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.

​

Checking a refusal yourself

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

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.