MentionFlow AI
Open app
DocsAPI & MCP

Errors

The JSON error shapes and status codes for the REST read API, the crawler-ingest endpoint, and the MCP JSON-RPC transport.

Errors are JSON with Content-Type: application/json. The shape depends on the surface you hit.

REST read errors

Read endpoints (/overview, /prompts, /competitors, /sources, /answers, /brands, /shopping, /shopping-trend) return { "error": "<message>" }:

StatusBodyWhen
503{"error":"API disabled — set API_ACCESS_KEY"}The API is off for this deployment.
401{"error":"Unauthorized"}Missing or invalid key.
401{"error":"This API key expired on <date>. …"}The key has an expiry and it has passed.
403ingest-only messageAn ingest-scoped key was used on a read endpoint.
403IP-allowlist messageThe key has an IP allowlist and the request's address isn't on it.
404{"error":"No brands exist"}The workspace has no brands to report on.
404{"error":"Unknown brand"}The brand id is out of scope, or has no data window.
404{"error":"Unknown resource. …"}The path resource isn't one of the eight valid names.
429{"error":"Rate limit exceeded: 120 requests per minute per API key. Retry after <n>s.","retry_after_seconds":<n>}The key's rate limit bucket is empty. Honor Retry-After.

An out-of-scope brand id and a nonexistent one both return the same Unknown brand. The API never confirms whether another workspace's id is real.

The MCP endpoint returns the same 429 shape as plain HTTP. It is a transport-level refusal, not a JSON-RPC error object. The request was never parsed, so no tool ran.

Crawler-ingest errors

POST /api/v1/crawler-events returns { "error": "<message>" }:

StatusBodyWhen
503{"error":"API disabled — set API_ACCESS_KEY"}API off.
401{"error":"Unauthorized"}Missing or invalid key.
401 / 403expiry / IP-allowlist messageKey expiry and IP allowlists apply to ingest exactly as to reads.
404{"error":"Unknown brand"}The brand id is out of scope.
400{"error":"Empty body"}A non-verification request with a blank body.
413{"error":"Body over 10 MB — ship smaller batches"}Body over the 10 MB cap.

A successful ingest returns 200 with { "inserted", "matched", "totalLines", "unparsed" } (see Resource reference).

MCP (JSON-RPC) errors

The MCP endpoint speaks JSON-RPC 2.0. Keep transport errors and tool errors apart.

Transport errors mean a malformed request. They come back as JSON-RPC error objects:

CodeHTTPMessage
-32700400Parse error (invalid JSON)
-32600400Batch too large: <n> messages (max 10)
-32601200Method not found: <method>
-32602200Missing tool name

A GET /api/mcp returns 405 Method Not Allowed with an Allow: POST header. When the API is disabled it returns 503 {"error":"MCP disabled — set API_ACCESS_KEY"}.

Tool errors come from a tool that ran and failed, e.g. on an unknown brand_id. That is not an HTTP or JSON-RPC error. You get a normal tool result flagged isError: true, with the message as its text, e.g. {"error":"Unknown brand id: <id>"}. Check isError on tools/call results.

Related