MCP 错误目录

​

快速指引

• HTTP 状态码是传输层的回答。大多数 JSON-RPC 回复 —— 无论成功还是错误 —— 按 JSON-RPC 2.0 惯例都会以 HTTP 200 返回。只有当失败属于通用 HTTP 客户端必须响应的情况（鉴权、每日上限、服务不可用）且受益于 Retry-After / WWW-Authenticate 头时，handler 才会升级状态码。
• JSON-RPC error.code 是应用层的回答。共使用六个代码：-32001、-32029、-32600、-32601、-32602、-32603。handler 不会发出其他代码 —— 如果你看到了其他代码，请将其视为协议 bug 并提交 issue。
• 软行为信封是高频失败模式。tools/call 在 JSON-RPC 层成功（HTTP 200，无 error 字段），但位于 result.content[0].text 中的 JSON 携带了一个 _budget_exceeded 或 _jmespath_error 判别字段。只检查 JSON-RPC 信封的客户端会默默地把这些当作成功 —— 请解析 result.content[0].text，并在将该负载作为数据消费前检查是否存在前导下划线 _ 键。
• 已执行的调用仍计费。 _budget_exceeded、_jmespath_error 和工具执行错误（-32603）都发生在工具已运行之后，因此它们会消耗 Pro 每日配额槽位。只有预分发失败（如每日上限拒绝或配额预留服务失败）才不消耗槽位。
• 两条 401 路径都设置了 WWW-Authenticate，包含 realm="worldmonitor" 以及指向 /.well-known/oauth-protected-resource 的 resource_metadata 指针。支持 RFC 9728 的客户端（Claude Desktop、MCP Inspector）会凭此头自动跳转 OAuth 流程，无需进一步干预。

​

JSON-RPC 错误代码

​

-32001 —— 未鉴权 / 凭证无效

1. 既无 Authorization bearer 也无 X-WorldMonitor-Key —— 客户端在调用 /mcp 时未携带任何凭证。
2. Authorization: Bearer <token> 但 <token> 无效或已过期 —— 令牌无法解析到上下文（被撤销 / TTL 过期 / 从未由 /api/oauth/token 签发）。
3. X-WorldMonitor-Key: <key> 但 <key> 不在有效集合中 —— API key 错误。
4. OAuth 令牌可解析但 Pro MCP 令牌行缺失或跨绑定 —— mcpTokenId 不再映射到该 userId。通常是 Settings → Connected MCP clients 中的撤销操作所致。
5. OAuth 令牌可解析但订阅已失效 —— 权益重新检查发现 tier < 1、mcpAccess !== true 或 validUntil < now。包括权益服务不可用时的故障关闭路径。

{
  "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 —— 被限流（每分钟或每日）

{
  "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 —— 请求信封无效

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

​

-32601 —— 方法未找到

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

​

-32602 —— 参数无效

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

​

-32603 —— 内部错误

{
  "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 状态码

• 405 携带空主体来自 JSON-RPC 之前的方法校验。handler 接受 POST（JSON-RPC 路径）、GET（独立 SSE 流 / Last-Event-ID 重放通道）、HEAD（以 200 ack 携带 Content-Type: application/json，供可用性探测使用）和 OPTIONS（CORS 预检）。无 Last-Event-ID 的裸 GET 也返回 405（不提供独立流）。其他方法得到 405 + Allow: POST, GET, HEAD, OPTIONS。该端点不强制 Origin 允许列表：它通告通配 CORS，并通过显式 Authorization / X-WorldMonitor-Key 头鉴权，因此浏览器来源客户端（任意来源）均被接受。

​

软行为信封

1. 将 result.content[0].text 解析为 JSON。
2. 检查解析后的对象顶层是否含有 _budget_exceeded 或 _jmespath_error 键。若有，视为错误，不要将同侪字段当作数据消费。
3. 否则，将解析后的对象视为该工具的正常响应（缓存工具会将其包成 { cached_at, stale, data }；RPC 工具返回其声明的形状）。

​

_budget_exceeded —— 响应超出每工具预算

{
  "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 —— 判别字段。始终字面为 true；绝不会出现在成功响应中。
• budget_bytes: number —— 响应所对照检查的每工具预算。
• actual_bytes: number —— 所有收窄后序列化响应的 UTF-8 字节长度。
• hint: string —— 恢复建议。文本因调用者是否已传入 jmespath 参数而异；两种措辞都要求你收窄结果。

​

_jmespath_error —— 投影失败

{
  "_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"]
}

​

其他工具专属信封

• describe_tool 返回 { "error": "missing_tool_name", "hint": "..." } 或 { "error": "unknown_tool", "requested": "...", "available": [...] }。配额豁免 —— 错误输入不消耗配额槽位。见 工具参考 → describe_tool。

​

路线图

• 预算超限时自动摘要。 未来的协议修订可能让 _budget_exceeded 响应在信封之外内联附带一个服务端构建的摘要（一个带注解的内容块），适用于摘要定义良好的那部分工具。推迟到生产遥测数据能证明每工具权衡合理之时。

​

另请参阅

• MCP Server 概览 —— 端点、鉴权模式、OAuth 配置、套餐与配额。
• JMESPath 投影指南 —— 投影语法 + 12 个示例；学习如何修复 _jmespath_error 以及从 _budget_exceeded 恢复的正确去处。
• MCP 工具参考 —— 每工具参数、响应形状及每工具软信封（例如 describe_tool）。
• MCP 快速入门 —— 五分钟从零到首次调用的入门。
• JSON-RPC 2.0 规范 —— 本目录通篇引用的线上信封形状。
• RFC 9728 —— OAuth 2.0 Protected Resource Metadata —— WWW-Authenticate 的 resource_metadata 指针的含义。