# `Hermolaos.Protocol.Errors`
[🔗](https://github.com/nyo16/hermolaos/blob/v0.5.0/lib/hermolaos/protocol/errors.ex#L1)

JSON-RPC 2.0 and MCP error codes and error handling utilities.

## Standard JSON-RPC 2.0 Error Codes

| Code   | Message          | Description                           |
|--------|------------------|---------------------------------------|
| -32700 | Parse error      | Invalid JSON                          |
| -32600 | Invalid Request  | Not a valid JSON-RPC request          |
| -32601 | Method not found | Method doesn't exist                  |
| -32602 | Invalid params   | Invalid method parameters             |
| -32603 | Internal error   | Internal JSON-RPC error               |

## MCP-Specific Error Codes (reserved: -32000 to -32099)

| Code   | Description                                       |
|--------|---------------------------------------------------|
| -32000 | Connection closed unexpectedly                    |
| -32001 | Request timed out                                 |
| -32002 | Request was cancelled                             |
| -32003 | Resource not found                                |

## Examples

    # Create an error struct
    error = Hermolaos.Protocol.Errors.method_not_found("unknown/method")

    # Convert to exception for raising
    raise Hermolaos.Protocol.Errors.to_exception(error)

    # Parse error from JSON-RPC response
    {:ok, error} = Hermolaos.Protocol.Errors.from_response(response)

# `error_code`

```elixir
@type error_code() ::
  :parse_error
  | :invalid_request
  | :method_not_found
  | :invalid_params
  | :internal_error
  | :connection_closed
  | :request_timeout
  | :request_cancelled
  | :resource_not_found
  | :url_elicitation_required
```

# `t`

```elixir
@type t() :: %Hermolaos.Protocol.Errors{
  code: integer(),
  data: term(),
  message: String.t()
}
```

# `code_to_name`

```elixir
@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

# `connection_closed`

```elixir
@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}

# `connection_closed_code`

```elixir
@spec connection_closed_code() :: integer()
```

Returns the MCP connection closed error code (-32000)

# `from_response`

```elixir
@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}

# `internal_error`

```elixir
@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"}

# `internal_error_code`

```elixir
@spec internal_error_code() :: integer()
```

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

# `invalid_params`

```elixir
@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"}}

# `invalid_params_code`

```elixir
@spec invalid_params_code() :: integer()
```

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

# `invalid_request`

```elixir
@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"}

# `invalid_request_code`

```elixir
@spec invalid_request_code() :: integer()
```

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

# `method_not_found`

```elixir
@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}

# `method_not_found_code`

```elixir
@spec method_not_found_code() :: integer()
```

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

# `parse_error`

```elixir
@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}

# `parse_error_code`

```elixir
@spec parse_error_code() :: integer()
```

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

# `request_cancelled`

```elixir
@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"}

# `request_cancelled_code`

```elixir
@spec request_cancelled_code() :: integer()
```

Returns the MCP request cancelled error code (-32002)

# `request_timeout`

```elixir
@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}}

# `request_timeout_code`

```elixir
@spec request_timeout_code() :: integer()
```

Returns the MCP request timeout error code (-32001)

# `resource_not_found`

```elixir
@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}

# `resource_not_found_code`

```elixir
@spec resource_not_found_code() :: integer()
```

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

# `retriable?`

```elixir
@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

# `standard_error?`

```elixir
@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

# `to_exception`

```elixir
@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"

# `to_map`

```elixir
@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"}

# `url_elicitation_required`

```elixir
@spec url_elicitation_required(term()) :: t()
```

Creates a URL elicitation required error.

Used when a server requires URL-based elicitation for an operation.

# `url_elicitation_required_code`

```elixir
@spec url_elicitation_required_code() :: integer()
```

Returns the MCP URL elicitation required error code (-32042)

---

*Consult [api-reference.md](api-reference.md) for complete listing*