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. Six codes are in use: -32001, -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.
• Both 401 paths set 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.
5. OAuth token resolves but the subscription went away — entitlement re-check found tier < 1, mcpAccess !== true, or validUntil < now. Includes the entitlements-service-unavailable fail-closed path.

{
  "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."
  }
}

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

​

-32029 — Rate limited (per-minute OR daily)

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

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

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 standalone SSE stream / Last-Event-ID replay channel), HEAD (a 200 ack with Content-Type: application/json, used by uptime probes), and OPTIONS (CORS preflight). A bare GET with no Last-Event-ID also 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.