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.
• Quota rollback is automatic for soft envelopes. _budget_exceeded and tool-execution errors (-32603) refund the Pro daily-quota slot — you do not pay for a response you cannot use. _jmespath_error does NOT refund, because the tool fetch succeeded; the user-supplied projection is what failed.
• 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

• 403 with a plain Forbidden body comes from origin-validation BEFORE the JSON-RPC layer runs. Don’t try to JSON.parse the body. This is only relevant to browser-origin clients; CLI clients, Claude Desktop, and curl send no Origin header and are exempt.
• 405 with an empty body comes from method-validation BEFORE JSON-RPC. The handler accepts POST (the JSON-RPC path), HEAD (a 200 ack with Content-Type: application/json, used by uptime probes), and OPTIONS (CORS preflight). Anything else gets 405 + Allow: POST, HEAD, OPTIONS.

​

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.