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 which 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 turned off for this deployment.
401{"error":"Unauthorized"}Missing or invalid key.
403ingest-only messageAn ingest-scoped key was used on a read endpoint.
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 return the identical Unknown brand — the API never confirms whether another workspace's id is real.

The MCP endpoint returns the same 429 shape as plain HTTP (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.
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 exceeds 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. Distinguish transport errors from tool errors:

Transport errors — malformed requests, returned 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 — a tool that runs but fails (e.g. an unknown brand_id) does not raise an HTTP or JSON-RPC error. It returns a normal tool result flagged isError: true, whose text content is the message, e.g. {"error":"Unknown brand id: <id>"}. Check isError on tools/call results.

Related