Problem
ToolHive emits JSON-RPC error code -32029 (CodeRateLimited, pkg/ratelimit/errors.go) on the wire — from the HTTP middleware (pkg/ratelimit/middleware.go:171-183) and, since #6033, on the vMCP Modern (2026-07-28) dispatch path via writeModernCodedError.
The draft MCP spec (verified live at modelcontextprotocol.io/specification/draft/basic, "Error Codes", 2026-07-28) partitions the JSON-RPC implementation-defined range and reserves our band:
-32020 to -32099 — reserved for the MCP specification. Error codes in this sub-range are defined exclusively by the MCP specification and recorded in the schema. Implementations MUST NOT emit any code from this sub-range that is not defined by this specification and MUST use defined codes only with their specified meanings.
Only -32020 (HeaderMismatch), -32021 (MissingRequiredClientCapability) and -32022 (UnsupportedProtocolVersion) are defined. -32029 is therefore non-conformant.
The CodeRateLimited comment cites RFC THV-0057's "implementation-defined code in the -32000 to -32099 range" — a premise the spec partition has invalidated.
Conformant path
Per the same spec section:
New error codes for purposes not defined by this specification SHOULD be allocated outside the JSON-RPC reserved range (-32768 to -32000); the remainder of the integer space is available for application-defined errors.
- Reallocate
CodeRateLimited outside -32768..-32000 (the spec defines no rate-limiting code and no retryAfterSeconds convention, so this stays application-defined).
data.retryAfterSeconds can stay — error data "MAY include a data member with additional information of any type".- Update RFC THV-0057 and the
CodeRateLimited comment.
- Note this is a wire-visible change for any client pattern-matching
-32029.
Affected
Surfaced by review on #6033. Refs #5743.
Problem
ToolHive emits JSON-RPC error code
-32029(CodeRateLimited,pkg/ratelimit/errors.go) on the wire — from the HTTP middleware (pkg/ratelimit/middleware.go:171-183) and, since #6033, on the vMCP Modern (2026-07-28) dispatch path viawriteModernCodedError.The draft MCP spec (verified live at
modelcontextprotocol.io/specification/draft/basic, "Error Codes", 2026-07-28) partitions the JSON-RPC implementation-defined range and reserves our band:Only
-32020(HeaderMismatch),-32021(MissingRequiredClientCapability) and-32022(UnsupportedProtocolVersion) are defined.-32029is therefore non-conformant.The
CodeRateLimitedcomment cites RFC THV-0057's "implementation-defined code in the -32000 to -32099 range" — a premise the spec partition has invalidated.Conformant path
Per the same spec section:
CodeRateLimitedoutside-32768..-32000(the spec defines no rate-limiting code and noretryAfterSecondsconvention, so this stays application-defined).data.retryAfterSecondscan stay — errordata"MAY include a data member with additional information of any type".CodeRateLimitedcomment.-32029.Affected
pkg/ratelimit/errors.go(CodeRateLimited)pkg/ratelimit/middleware.go:171-183writeModernCodedError(Replace vMCP Modern kill-switch with a capability gate #6033) andconversion.ErrorToToolResultdocs/arch/10-virtual-mcp-architecture.md(gate section)Surfaced by review on #6033. Refs #5743.