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 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.