Error codes
Every refusal the StoreScope Analytics MCP server (https://storescope.devino.ca/mcp) and API (https://storescope.devino.ca/api/tools/<tool name>) can answer, what it means and what to do.
All codes
invalid_token · rate_limited · payload_too_large · unknown_tool · invalid_body · method_not_allowed · -32700 · -32600 · -32601 · -32000 · -32603 · -32602 · SCOPE_MISSING · WRONG_PRODUCT · CONFIRMATION_REQUIRED · CONSENT_REVOKED · TOOL_EXECUTION_FAILED · status: rejected · status: failed
Request refusals
Answered before any tool runs. The HTTP status is the one shown; the body is JSON.
invalid_token 401 MCP and API
No credential was sent, or the one sent is not valid for this host. The WWW-Authenticate header carries the reason and the resource_metadata address an MCP client uses to sign in again.
What to do: Send `Authorization: Bearer <key>` with a workspace key from the MCP & API page, or sign in again through your AI client.
{"error":"invalid_token","message":"<reason>"}| Reason or message | Meaning |
|---|---|
workspace key not recognised or revoked | The key was revoked, or mistyped. Create a new one on the MCP & API page. |
not a token from this server | The bearer is neither a workspace key nor a token this host issued. |
access token expired; refresh it | Your AI client refreshes it on its own; if not, connect again. |
this token is for another server, not <host>/mcp | A StoreScope Analytics token was sent to Storevisor, or the reverse. Each product host has its own connection. |
token carries no workspace; connect again | Connect again and pick a workspace. |
you are no longer a member of this workspace | Your membership was removed. Ask an owner for a new invite link. |
this connection was revoked; connect again | The AI app was disconnected on the MCP & API page. |
access token could not be verified | The token is damaged or was signed with an old key. Connect again. |
rate_limited 429 MCP and API
More than 60 calls a minute from one key or one AI connection (the answer carries retry_after_s and a Retry-After header), or more than 30 refused credentials a minute from one address (no Retry-After).
What to do: Wait the number of seconds in Retry-After (or a minute), then repeat the call. Calls refill steadily: spread them out rather than sending them in bursts.
{"error":"rate_limited","retry_after_s":12}payload_too_large 413 MCP and API
The request body is over 256 KB. The answer is the plain text "payload too large" (the server-wide body limit), or this JSON from the MCP endpoint's own check.
What to do: Send less in one call (shorter text, fewer items).
payload too largeunknown_tool 404 API
The name after /api/tools/ is not a tool of either product.
What to do: Use a name from the API reference. Names are lower case with underscores.
{"error":"unknown_tool"}invalid_body 400 API
The request body is not JSON.
What to do: Send the tool's arguments as one JSON object (or an empty body for a tool without arguments), with Content-Type: application/json.
{"error":"invalid_body","message":"body must be a JSON object of arguments"}method_not_allowed 405 MCP
A GET to /mcp. The server is stateless: JSON-RPC over POST only, no event stream and no sessions.
What to do: POST each JSON-RPC message.
{"error":"method_not_allowed","message":"POST JSON-RPC only (stateless, no SSE)."}-32700 400 MCP
The JSON-RPC body is not JSON.
What to do: Send one valid JSON-RPC message per POST.
{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error: body is not JSON"}}-32600 400 MCP
The body is a JSON-RPC batch (an array), or not a JSON-RPC object.
What to do: Send one message per POST; batches are not supported.
{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"JSON-RPC batch requests are not supported; send one message per POST"}}-32601 200 (MCP), 400 (API) MCP and API
A JSON-RPC method this server does not offer.
What to do: Use initialize, tools/list and tools/call (and resources/prompts on StoreScope Analytics).
{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"Method not found"}}-32000 503 MCP and API
Every worker that runs tools is in use right now.
What to do: Wait the Retry-After seconds (5) and repeat the call.
{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"StoreScope is busy right now; retry in a few seconds"}}-32603 502 MCP and API
The tool ran out of time (15 minutes), or its worker stopped without answering. The error was logged.
What to do: Repeat a read. Before repeating a write, check its result first (a release or listing read): a write that ran out of time may have reached the store.
{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"the tool ran out of time"}}| Reason or message | Meaning |
|---|---|
the tool ran out of time | The call took longer than 15 minutes. |
the request failed; try again | The worker stopped without an answer. |
Tool refusals
A tool call that was refused. Over MCP it is a tool result with isError: true whose text (and structuredContent) is the JSON below; over the API it is that JSON with status 400.
-32602 400 MCP and API
The arguments do not match the tool's input schema (a missing required field, a wrong type, a value out of range). Nothing ran.
What to do: Fix the arguments named in the message; the API reference lists each tool's fields.
"MCP error -32602: Input validation error: Invalid arguments for tool <tool>: ..." (MCP: a tool result with isError; API: that text as the JSON body)SCOPE_MISSING 400 MCP and API
The connection or key may not use this tool. In practice: a write tool called with read-only access (a read key, a connection approved without "make changes", a viewer, or a workspace whose owner turned AI changes off). Carries requiredScope.
What to do: Use a read-and-write key, or connect again and tick the box that allows changes. A viewer, or a workspace with AI changes off, stays read-only whatever the key says.
{"code":"SCOPE_MISSING","message":"<tool> requires the \"listings:write\" scope; ...","requiredScope":"listings:write"}WRONG_PRODUCT 400 MCP and API
The tool belongs to the other product: StoreScope Analytics tools run on its host, Storevisor tools on its own. Carries product.
What to do: Call it on the other product's host. The same account and workspace work there; the AI connection or key is per host.
{"code":"WRONG_PRODUCT","message":"<tool> belongs to the ops product; ...","product":"ops"}CONFIRMATION_REQUIRED 400 MCP and API
A write was called with apply: true, but the confirmToken is missing or does not match. Nothing reached the store, and no new token was issued. Carries reason.
What to do: Call the tool again without apply to get a new preview and confirm_token, then repeat the SAME arguments (with any commit_args merged in) plus apply: true and that confirmToken within 10 minutes.
{"code":"CONFIRMATION_REQUIRED","message":"apply:true was refused (expired) — ...","reason":"expired"}| Reason or message | Meaning |
|---|---|
malformed | No token, or not a token. |
bad_signature | The token was altered, or was issued in another workspace. |
expired | The token is older than 10 minutes. |
mismatch | The arguments, the tool, the person or the AI connection differ from the preview's. |
reused | The token was already used. Each token commits once. |
CONSENT_REVOKED 400 MCP and API
The approval behind an OAuth connection was revoked or narrowed. The cloud answers a revoked connection earlier, with 401 invalid_token ("this connection was revoked; connect again"), so this code is not expected from it.
What to do: Connect again.
{"code":"CONSENT_REVOKED","message":"..."}TOOL_EXECUTION_FAILED 400 MCP and API
The tool could not do what was asked. A refusal the tool wrote itself (a store that is not connected, a store's own refusal, an argument the store would not accept) is passed on word for word; anything else is a generic message with an audit_id, and the details are in our log.
What to do: Read the message: it says what to change. With an audit_id, try again, and quote the number on the Support page if it stays.
{"code":"TOOL_EXECUTION_FAILED","message":"...","audit_id":123}| Reason or message | Meaning |
|---|---|
<tool> needs <a store connection>, and this workspace has none yet. Connect it on the Connections page, then call <tool> again. Nothing was read or changed. | Connect that store (see Connect your stores). |
<tool> is not available on this server | The tool is not offered in the cloud (uploads, the Resolution Center, App Privacy). |
unknown tool "<name>" — call tools/list for the tools this token can use | The name is not a tool. |
<tool> failed; see server log (audit row <n>) | An unexpected failure, logged under that number. |
Write outcomes
Not errors of the call: a write answered normally, with a status saying it did not happen.
status: rejected 200 MCP and API
A write's preview was refused (invalid input for the store, a missing prerequisite, a value identical to the current one). The answer lists the reasons and carries commit: not_available and commit_reason. No token is issued; nothing reached the store.
What to do: Fix what the reasons say and preview again.
{"status":"rejected","explanation":"...","commit":"not_available","commit_reason":"This preview was REJECTED and cannot be committed: ..."}status: failed 200 MCP and API
A confirmed write reached the store and the store refused it. The explanation carries the store's answer, and the workspace's Activity page lists the call as failed.
What to do: Read the explanation. Preview again before retrying: the store's state may have moved.
{"status":"failed","change_id":42,"explanation":"<the store's answer>", ...}Connection errors
Errors shown while connecting a store are in each connection guide. The request format is in the API reference.