@spec code_to_name(integer()) :: error_code() | :unknown

Converts an error code to its symbolic name.

Examples

iex> Hermolaos.Protocol.Errors.code_to_name(-32700)
:parse_error

iex> Hermolaos.Protocol.Errors.code_to_name(-99999)
:unknown

@spec connection_closed(term()) :: t()

Creates a connection closed error.

Examples

iex> Hermolaos.Protocol.Errors.connection_closed()
%Hermolaos.Protocol.Errors{code: -32000, message: "Connection closed", data: nil}

@spec connection_closed_code() :: integer()

Returns the MCP connection closed error code (-32000)

@spec from_response(map()) :: {:ok, t()} | {:error, :not_an_error | :invalid_error}

Parses an error from a JSON-RPC error response.

Examples

iex> response = %{"error" => %{"code" => -32601, "message" => "Method not found"}}
iex> Hermolaos.Protocol.Errors.from_response(response)
{:ok, %Hermolaos.Protocol.Errors{code: -32601, message: "Method not found", data: nil}}

iex> Hermolaos.Protocol.Errors.from_response(%{"result" => %{}})
{:error, :not_an_error}

@spec internal_error(term()) :: t()

Creates an internal error.

Examples

iex> Hermolaos.Protocol.Errors.internal_error("Database connection failed")
%Hermolaos.Protocol.Errors{code: -32603, message: "Internal error", data: "Database connection failed"}

@spec internal_error_code() :: integer()

Returns the JSON-RPC internal error code (-32603)

@spec invalid_params(term()) :: t()

Creates an invalid params error.

Examples

iex> Hermolaos.Protocol.Errors.invalid_params(%{field: "name", reason: "required"})
%Hermolaos.Protocol.Errors{code: -32602, message: "Invalid params", data: %{field: "name", reason: "required"}}

@spec invalid_params_code() :: integer()

Returns the JSON-RPC invalid params error code (-32602)

@spec invalid_request(term()) :: t()

Creates an invalid request error.

Examples

iex> Hermolaos.Protocol.Errors.invalid_request("Missing method field")
%Hermolaos.Protocol.Errors{code: -32600, message: "Invalid Request", data: "Missing method field"}

@spec invalid_request_code() :: integer()

Returns the JSON-RPC invalid request error code (-32600)

@spec method_not_found(String.t()) :: t()

Creates a method not found error.

Examples

iex> Hermolaos.Protocol.Errors.method_not_found("unknown/method")
%Hermolaos.Protocol.Errors{code: -32601, message: "Method not found: unknown/method", data: nil}

@spec method_not_found_code() :: integer()

Returns the JSON-RPC method not found error code (-32601)

@spec parse_error(term()) :: t()

Creates a parse error (invalid JSON).

Examples

iex> Hermolaos.Protocol.Errors.parse_error()
%Hermolaos.Protocol.Errors{code: -32700, message: "Parse error", data: nil}

@spec parse_error_code() :: integer()

Returns the JSON-RPC parse error code (-32700)

@spec request_cancelled(term()) :: t()

Creates a request cancelled error.

Examples

iex> Hermolaos.Protocol.Errors.request_cancelled("User cancelled")
%Hermolaos.Protocol.Errors{code: -32002, message: "Request cancelled", data: "User cancelled"}

@spec request_cancelled_code() :: integer()

Returns the MCP request cancelled error code (-32002)

@spec request_timeout(String.t(), integer() | nil) :: t()

Creates a request timeout error.

Examples

iex> Hermolaos.Protocol.Errors.request_timeout("tools/call", 30000)
%Hermolaos.Protocol.Errors{code: -32001, message: "Request timeout: tools/call", data: %{timeout_ms: 30000}}

@spec request_timeout_code() :: integer()

Returns the MCP request timeout error code (-32001)

@spec resource_not_found(String.t()) :: t()

Creates a resource not found error.

Examples

iex> Hermolaos.Protocol.Errors.resource_not_found("file:///missing.txt")
%Hermolaos.Protocol.Errors{code: -32003, message: "Resource not found: file:///missing.txt", data: nil}

@spec resource_not_found_code() :: integer()

Returns the MCP resource not found error code (-32003)

@spec retriable?(integer() | t()) :: boolean()

Checks if an error is retriable (connection issues, timeouts).

Examples

iex> Hermolaos.Protocol.Errors.retriable?(-32000)
true

iex> Hermolaos.Protocol.Errors.retriable?(-32601)
false

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

Checks if an error is a standard JSON-RPC error (vs MCP-specific).

Examples

iex> Hermolaos.Protocol.Errors.standard_error?(-32700)
true

iex> Hermolaos.Protocol.Errors.standard_error?(-32000)
false

@spec to_exception(t()) :: Hermolaos.Error.t()

Converts an error struct to a Hermolaos.Error exception.

Examples

iex> error = Hermolaos.Protocol.Errors.method_not_found("ping")
iex> exception = Hermolaos.Protocol.Errors.to_exception(error)
iex> exception.message
"MCP Error -32601: Method not found: ping"

@spec to_map(t()) :: map()

Converts an error struct to a map suitable for JSON-RPC response.

Examples

iex> error = %Hermolaos.Protocol.Errors{code: -32600, message: "Invalid", data: nil}
iex> Hermolaos.Protocol.Errors.to_map(error)
%{"code" => -32600, "message" => "Invalid"}