MCP Errors#

Interpret current OAuth-edge, protected-runtime, rate-limit, and narrow commerce errors.

Overview#

The current errors distinguish an OAuth-edge failure from the protected runtime that is not yet customer available.

Status or code	Meaning	Action
`401 invalid_token`	The protected request has no accepted bearer token	Start again from a supported client authorization flow; do not paste a token manually
`400 invalid_request`	The authorization request is malformed or outside policy	Check the exact callback, PKCE, resource, and requested scopes
`429 temporarily_unavailable`	Registration, authorization, or token ingress is rate limited	Wait at least the `Retry-After` value, currently 60 seconds
`404 tool_not_available`	The current protected runtime does not implement the method or named tool	Treat the customer MCP service as unavailable
JSON-RPC `-32601`	The requested method is not available for the token or organization	Check MCP Tool Availability
JSON-RPC `-32602`	The narrow credits method received unsupported arguments	Remove unrecognized arguments only in a controlled test
`result.isError: true`	A narrow commerce read could not complete	Preserve the sanitized result and timestamp

An unauthenticated 401 means the route requires OAuth. A 404 for initialize or tools/list means the current tool runtime is unavailable.

When reporting a problem, include the client name and version, timestamp, endpoint path, status, and sanitized error code. Never include tokens, authorization codes, cookies, client-verifier values, or project data.