MCP Error Catalog

​

Quick orientation

• HTTP status is the transport-layer answer. Most JSON-RPC replies — successes AND errors — come back as HTTP 200, per the JSON-RPC 2.0 convention. The handler only escalates the status when the failure is something a generic HTTP client must react to (auth, daily cap, service unavailable) and benefits from a Retry-After / WWW-Authenticate header.
• JSON-RPC error.code is the application-layer answer. Nine codes are in use: -32001, -32002, -32003, -32004, -32029, -32600, -32601, -32602, -32603. The handler never emits another code — if you see one, treat it as a wire bug and file an issue.
• Soft-behavior envelopes are the high-volume failure mode. tools/call succeeds at the JSON-RPC layer (HTTP 200, no error field), but the JSON sitting inside result.content[0].text carries a _budget_exceeded or _jmespath_error discriminator. Clients that only inspect the JSON-RPC envelope will silently treat these as successes — parse result.content[0].text and check for a leading _ key before consuming the payload as data.
• Executed calls stay charged. _budget_exceeded, _jmespath_error, and tool-execution errors (-32603) all happen after the tool has run, so they consume the Pro daily-quota slot. Only pre-dispatch failures such as daily-cap rejection or quota-reservation service failure avoid charging the slot.
• Every 401 sets WWW-Authenticate with realm="worldmonitor" and a resource_metadata pointer at /.well-known/oauth-protected-resource. RFC 9728-aware clients (Claude Desktop, MCP Inspector) bounce through the OAuth flow on this header without further intervention.

​

JSON-RPC error codes

​

-32001 — Unauthenticated / invalid credentials

1. No Authorization bearer AND no X-WorldMonitor-Key — the client called /mcp with no credentials.
2. Authorization: Bearer <token> but <token> is invalid or expired — the token didn’t resolve to a context (revoked / TTL expired / never minted by /api/oauth/token).
3. X-WorldMonitor-Key: <key> but <key> isn’t in the valid set — the API key is wrong.
4. OAuth token resolves but the Pro MCP token row is missing or cross-bound — the mcpTokenId no longer maps to the userId. Typically a revoke from Settings → Connected MCP clients. Not in this list, deliberately: a caller whose subscription is inactive. A confirmed free account (a configured no-row result or an internally consistent tier-0 row) is admitted onto the free-account allowance (see -32029 and -32002 below). A provider-confirmed lapse follows the same free-account path: the shared entitlement gate treats the ended coverage as a confirmed free state. An expired or disabled paid entitlement without that lapse returns terminal -32002 at HTTP 403 because re-authenticating cannot fix it. An entitlement lookup that fails or cannot be verified returns a retryable -32603 at HTTP 503 — it is an availability failure, not a verdict about the caller.

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32001,
    "message": "Authentication required. Use OAuth (/oauth/token) or pass your API key via X-WorldMonitor-Key header.",
    "data": {
      "reason": "no-account",
      "nextStep": "Sign in at the upgrade URL, connect WorldMonitor MCP with your account, or subscribe to Pro for the full daily allowance.",
      "upgradeUrl": "https://worldmonitor.app/pro?utm_source=mcp&utm_medium=agent&utm_campaign=mcp-paid-funnel"
    }
  }
}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="worldmonitor", resource_metadata="https://worldmonitor.app/.well-known/oauth-protected-resource"
Content-Type: application/json

​

-32002 — Terminal entitlement denial

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32002,
    "message": "Subscription lapsed. Re-authenticating will not help — resubscribe to restore access.",
    "data": {
      "code": "subscription_lapsed",
      "reason": "lapsed-subscription",
      "nextStep": "Resubscribe at the upgrade URL. The existing credential stays valid — re-authenticating will not restore access.",
      "upgradeUrl": "https://worldmonitor.app/pro?utm_source=mcp&utm_medium=agent&utm_campaign=mcp-paid-funnel"
    }
  }
}

HTTP/1.1 403 Forbidden
Cache-Control: no-store
X-Billing-Verification: subscription_lapsed
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32002,
    "message": "This tool requires a WorldMonitor Pro subscription.",
    "data": {
      "reason": "upgrade-required",
      "nextStep": "The free allowance covers cached-data tools only. Call one of those, or subscribe to Pro at the upgrade URL for the full tool set.",
      "upgradeUrl": "https://worldmonitor.app/pro?utm_source=mcp&utm_medium=agent&utm_campaign=mcp-paid-funnel"
    }
  }
}

​

-32003 — Required data inputs unavailable

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32003,
    "message": "Required data inputs are unavailable",
    "data": {
      "retryable": true,
      "stale": true,
      "unavailable_inputs": ["news:insights:v1"],
      "failed_inputs": []
    }
  }
}

​

-32004 — SSE replay cursor not found

​

-32029 — Rate limited (per-minute, daily cap, or free allowance)

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded. Max 60 requests per minute per user."
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32029,
    "message": "Daily MCP quota exceeded (50/day). Resets at next UTC midnight."
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32029,
    "message": "Free-account MCP allowance exhausted for today.",
    "data": {
      "reason": "allowance-exhausted",
      "nextStep": "Wait until the next UTC day for another free allowance window, or upgrade to Pro for a higher daily limit.",
      "upgradeUrl": "https://worldmonitor.app/pro?utm_source=mcp&utm_medium=agent&utm_campaign=mcp-paid-funnel"
    }
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 41200
Content-Type: application/json

​

-32600 — Invalid request envelope

{
  "jsonrpc": "2.0",
  "id": null,
  "error": { "code": -32600, "message": "Invalid request: missing method" }
}

​

-32601 — Method not found

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": { "code": -32601, "message": "Method not found: tools/run" }
}

​

-32602 — Invalid params

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": { "code": -32602, "message": "Unknown tool: get_marekt_data" }
}

​

-32603 — Internal error

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": { "code": -32603, "message": "Internal error: data fetch failed" }
}

{
  "jsonrpc": "2.0",
  "id": null,
  "error": { "code": -32603, "message": "Auth service temporarily unavailable. Try again." }
}

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

​

HTTP statuses

• 405 with an empty body comes from method-validation BEFORE JSON-RPC. The handler accepts POST (the JSON-RPC path), GET (the Last-Event-ID SSE replay channel, or — with no SSE Accept — the 200 markdown server guide), HEAD (same routing as GET: replay ack, guide headers, or a JSON 200 ack on non-/mcp pathnames used by uptime probes), and OPTIONS (CORS preflight). An SSE-flavoured GET with no Last-Event-ID returns 405 (no standalone stream is offered). Anything else gets 405 + Allow: POST, GET, HEAD, OPTIONS. The endpoint enforces no Origin allowlist: it advertises wildcard CORS and authenticates by explicit Authorization / X-WorldMonitor-Key header, so browser-origin clients (any origin) are accepted.

​

Soft-behavior envelopes

1. Parse result.content[0].text as JSON.
2. Check whether the parsed object has a _budget_exceeded or _jmespath_error key at its top level. If yes, treat as an error and do not consume sibling fields as data.
3. Otherwise, treat the parsed object as the tool’s normal response (cache tools wrap it as { cached_at, stale, data }; RPC tools return their declared shape).

​

_budget_exceeded — response too big for the per-tool budget

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"_budget_exceeded\":true,\"budget_bytes\":65536,\"actual_bytes\":142337,\"hint\":\"Response still exceeds tool output budget after JMESPath projection. Use a more selective expression to project fewer fields, or apply tool-level filters to narrow the result set.\"}"
      }
    ]
  }
}

{
  "_budget_exceeded": true,
  "budget_bytes": 65536,
  "actual_bytes": 142337,
  "hint": "Response still exceeds tool output budget after JMESPath projection. Use a more selective expression to project fewer fields, or apply tool-level filters to narrow the result set."
}

• _budget_exceeded: true — discriminator. Always literally true; never present on success responses.
• budget_bytes: number — the per-tool budget the response was checked against.
• actual_bytes: number — UTF-8 byte length of the serialised response after all narrowing.
• hint: string — recovery advice. The text varies based on whether the caller already passed a jmespath argument; both phrasings tell you to narrow the result.

​

_jmespath_error — projection failed

{
  "_jmespath_error": "invalid_expression: Parse error at column 32: …",
  "original_keys": ["stocks-bootstrap", "commodities-bootstrap", "crypto", "sectors", "etf-flows", "gulf-quotes", "fear-greed"]
}

​

expression_too_long

{
  "_jmespath_error": "expression_too_long: 1156 > 1024",
  "original_keys": ["stocks-bootstrap", "commodities-bootstrap", "crypto"]
}

​

invalid_expression

{
  "_jmespath_error": "invalid_expression: Parse error at column 32: expected one of [LBRACKET, DOT]",
  "original_keys": ["ucdp-events"]
}

​

projection_too_large

{
  "_jmespath_error": "projection_too_large: 412338 > 262144",
  "original_keys": ["ucdp-events"]
}

​

Other tool-specific envelopes

• describe_tool returns { "error": "missing_tool_name", "hint": "..." } or { "error": "unknown_tool", "requested": "...", "available": [...] }. Quota-exempt — bad input does not consume a quota slot. See Tools Reference → describe_tool.

​

Roadmap

• Auto-summarize on budget exceed. A future protocol revision may have _budget_exceeded responses ship a server-built summary inline (one annotated content block in addition to the envelope) for the subset of tools where a summary is well-defined. Deferred until production telemetry justifies the per-tool tradeoff.

​

See also

• MCP Server overview — endpoints, auth modes, OAuth setup, plans and quotas.
• JMESPath Projection Guide — projection grammar + 12 worked examples; the right place to learn how to fix _jmespath_error and recover from _budget_exceeded.
• MCP Tools Reference — per-tool parameters, response shapes, and per-tool soft envelopes (e.g. describe_tool).
• MCP Quickstart — five-minute zero-to-first-call onboarding.
• JSON-RPC 2.0 spec — the wire envelope shape the catalog references throughout.
• RFC 9728 — OAuth 2.0 Protected Resource Metadata — what the WWW-Authenticate resource_metadata pointer means.