ExMCP.Protocol.ErrorCodes (ex_mcp v1.0.0-rc.5)

Copy Markdown View Source

JSON-RPC 2.0 and MCP-specific error codes.

This module provides constants and helper functions for working with error codes in the MCP protocol. All error codes follow the JSON-RPC 2.0 specification with MCP-specific extensions.

Standard JSON-RPC 2.0 Error Codes

  • -32700 - Parse error: Invalid JSON was received
  • -32600 - Invalid Request: The JSON sent is not a valid Request object
  • -32601 - Method not found: The method does not exist or is not available
  • -32602 - Invalid params: Invalid method parameter(s)
  • -32603 - Internal error: Internal JSON-RPC error

MCP-Specific Error Codes

  • -32001 - Request cancelled: The request was cancelled by the client
  • -32002 - Consent required: User consent is required for the operation
  • -32003 - Consent denied: User denied consent for the operation
  • -32020 - Header mismatch
  • -32021 - Missing required client capability
  • -32022 - Unsupported protocol version
  • -32000 - Generic server error: Catch-all for server-side errors

Compatibility note

The existing 1.x API assigns -32002 to consent-required, resource-not-found, and prompt errors. Consequently, error_message(:resource_not_found) returns "Consent required". The collision is retained through 1.x to avoid changing public and wire values.

Usage

iex> ExMCP.Protocol.ErrorCodes.invalid_params()
-32602

iex> ExMCP.Protocol.ErrorCodes.error_message(:invalid_params)
"Invalid params"

iex> ExMCP.Protocol.ErrorCodes.is_protocol_error?(-32602)
true

Summary

Functions

consent_denied()

Consent denied: User denied consent for the operation

consent_required() deprecated

Consent required: User consent is required for the operation.

error_message(code)

Returns a human-readable error message for the given error code or atom.

error_response(code_or_atom, custom_message \\ nil)

Creates an error response map with the given code and message.

header_mismatch()

Header mismatch between negotiated protocol state and the request

internal_error()

Internal error: Internal JSON-RPC error

invalid_params()

Invalid params: Invalid method parameter(s)

invalid_request()

Invalid Request: The JSON sent is not a valid Request object

is_mcp_error?(code)

Checks if the given error code is an MCP-specific error.

is_protocol_error?(code)

Checks if the given error code is a standard JSON-RPC protocol error.

method_not_found()

Method not found: The method does not exist or is not available

missing_required_client_capability()

A required client capability was not declared

parse_error()

Parse error: Invalid JSON was received by the server

request_cancelled()

Request cancelled: The request was cancelled by the client

resource_not_found() deprecated

Resource not found: The requested resource does not exist.

server_error()

Generic server error: Catch-all for server-side errors

unsupported_protocol_version()

The requested protocol version is not supported

url_elicitation_required()

URL elicitation required: The server requires URL-mode elicitation

Functions

error_message(code)

@spec error_message(integer() | atom()) :: String.t()

Returns a human-readable error message for the given error code or atom.

Examples

iex> ExMCP.Protocol.ErrorCodes.error_message(-32602)
"Invalid params"

iex> ExMCP.Protocol.ErrorCodes.error_message(:invalid_params)
"Invalid params"

error_response(code_or_atom, custom_message \\ nil)

@spec error_response(atom() | integer(), String.t() | nil) :: map()

Creates an error response map with the given code and message.

Examples

iex> ExMCP.Protocol.ErrorCodes.error_response(:invalid_params, "Missing required field: name")
%{code: -32602, message: "Invalid params: Missing required field: name"}

header_mismatch()

Header mismatch between negotiated protocol state and the request

internal_error()

Internal error: Internal JSON-RPC error

invalid_params()

Invalid params: Invalid method parameter(s)

invalid_request()

Invalid Request: The JSON sent is not a valid Request object

is_mcp_error?(code)

@spec is_mcp_error?(integer()) :: boolean()

Checks if the given error code is an MCP-specific error.

Examples

iex> ExMCP.Protocol.ErrorCodes.is_mcp_error?(-32001)
true

iex> ExMCP.Protocol.ErrorCodes.is_mcp_error?(-32602)
false

is_protocol_error?(code)

@spec is_protocol_error?(integer()) :: boolean()

Checks if the given error code is a standard JSON-RPC protocol error.

Examples

iex> ExMCP.Protocol.ErrorCodes.is_protocol_error?(-32602)
true

iex> ExMCP.Protocol.ErrorCodes.is_protocol_error?(-32001)
false

method_not_found()

Method not found: The method does not exist or is not available

missing_required_client_capability()

A required client capability was not declared

parse_error()

Parse error: Invalid JSON was received by the server

request_cancelled()

Request cancelled: The request was cancelled by the client

resource_not_found()

This function is deprecated. The -32002 consent/resource/prompt collision is retained only for 1.x compatibility.

Resource not found: The requested resource does not exist.

This legacy constructor returns -32002, which also means consent-required and prompt error in 1.x. It is retained for compatibility.

server_error()

Generic server error: Catch-all for server-side errors

unsupported_protocol_version()

The requested protocol version is not supported

url_elicitation_required()

URL elicitation required: The server requires URL-mode elicitation