MCP error contract

The standard POM AI transport uses the following JSON-RPC 2.0 errors for protocol and MCP method failures.

Domain failures include a stable public code in error.data.code, for example pom_ai_mcp_unknown_tool, pom_ai_mcp_scope_denied, pom_ai_mcp_resource_not_found, or a tool-specific capability, gate, schema, object, or allowlist error.

Authentication can fail at the HTTP/REST boundary before a JSON-RPC method runs. Preserve both the HTTP status and the POM error code when available.

Native adapter errors

In WordPress MCP Adapter mode, a tool execution or permission failure returns result.isError: true with an explanatory text item. HTTP 200 alone does not establish success. The adapter does not preserve the standard transport’s error.data.code for tool execution failures; do not branch on translated text. Protocol, resource and prompt failures use the adapter’s JSON-RPC error responses.

Authentication failures may instead return an HTTP error before dispatch. Native mode returns 401 for missing/invalid credentials, 403 for denied transport access, 429 when its request quota is exhausted, and 503 when request limiting or the selected adapter dependency is unavailable. Session termination or expiry requires initialization of a new session. Native mode rejects JSON-RPC batches with HTTP 400.

Client behavior

• Match on codes when supplied, and check isError for native tool results; never branch on translated message text.
• Treat -32029 as a retry-later condition.
• Treat scope, capability, gate, and allowlist denial as configuration or authorization work, not transient failure.
• On a write timeout, read current state before retrying.
• Do not expose raw request bodies or credentials in user-facing diagnostics.

A successful tools/call has isError: false. Tool-domain failures are not returned as successful text content.

Related guides: transport, rate limiting, and safe support information.