# `ExMCP.Transport.Error`
[🔗](https://github.com/azmaveth/ex_mcp/blob/v1.0.0/lib/ex_mcp/transport/error.ex#L1)

Standardized error handling for MCP transports.

This module provides consistent error patterns and error handling functions
for all MCP transport implementations. It ensures that all transports return
errors in the same format for better client compatibility.

## Standard Error Types

- `:connection_error` - Connection establishment or maintenance failures
- `:transport_error` - Transport-level communication failures  
- `:security_violation` - Security policy violations
- `:validation_error` - Message or parameter validation failures
- `:timeout_error` - Operation timeout failures
- `:protocol_error` - Protocol-level violations or incompatibilities

## Usage

    # In transport implementations
    case some_operation() do
      {:ok, result} -> {:ok, result}
      {:error, reason} -> Error.transport_error(reason)
    end

    # Connection failures
    Error.connection_error(:server_not_available)

    # Security violations  
    Error.security_violation("Invalid origin")

# `error_reason`

```elixir
@type error_reason() :: atom() | String.t() | map()
```

# `error_type`

```elixir
@type error_type() ::
  :connection_error
  | :transport_error
  | :security_violation
  | :validation_error
  | :timeout_error
  | :protocol_error
```

# `connection_error`

```elixir
@spec connection_error(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized connection error.

Used when transport connection establishment or maintenance fails.

# `error_type?`

```elixir
@spec error_type?(
  {:error, {error_type(), any()}},
  error_type()
) :: boolean()
```

Checks if an error is of a specific type.

## Examples

    error = Error.connection_error(:timeout)
    Error.error_type?(error, :connection_error)  #=> true
    Error.error_type?(error, :transport_error)   #=> false

# `get_error_reason`

```elixir
@spec get_error_reason({:error, {error_type(), any()}} | any()) :: any()
```

Extracts the error reason from a standardized error tuple.

Returns the original error for non-standard formats.

# `get_error_type`

```elixir
@spec get_error_type({:error, {error_type(), any()}} | any()) ::
  error_type() | :unknown
```

Extracts the error type from a standardized error tuple.

Returns `:unknown` for non-standard error formats.

# `normalize_error`

```elixir
@spec normalize_error(any()) :: {:error, {error_type(), any()}}
```

Normalizes an error tuple to the standard format.

Converts various error formats into the standardized transport error format.

# `protocol_error`

```elixir
@spec protocol_error(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized protocol error.

Used when protocol-level violations or incompatibilities occur.

# `security_violation`

```elixir
@spec security_violation(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized security violation error.

Used when security policies are violated.

# `timeout_error`

```elixir
@spec timeout_error(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized timeout error.

Used when operations exceed their timeout limits.

# `transport_error`

```elixir
@spec transport_error(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized transport error.

Used for transport-level communication failures.

# `validate_connection`

```elixir
@spec validate_connection(any(), (any() -> boolean())) ::
  :ok | {:error, {error_type(), any()}}
```

Validates connection state before performing transport operations.

This helper provides consistent connection validation across all transports.
It should be called before send_message and receive_message operations.

## Examples

    case Error.validate_connection(state, &MyTransport.connected?/1) do
      :ok -> 
        # Proceed with operation
      {:error, reason} -> 
        # Handle disconnected state
    end

# `validate_connection_with_module`

```elixir
@spec validate_connection_with_module(any(), module()) ::
  :ok | {:error, {error_type(), any()}}
```

Validates connection state using the transport's connected?/1 function.

This is a convenience function for transports that implement the standard
connected?/1 callback.

# `validation_error`

```elixir
@spec validation_error(error_reason()) :: {:error, {error_type(), error_reason()}}
```

Creates a standardized validation error.

Used when message or parameter validation fails.

# `wrap_error`

```elixir
@spec wrap_error(error_type(), any()) :: {:error, {error_type(), any()}}
```

Wraps an arbitrary error in the standard transport error format.

This is useful for converting legacy error formats or third-party
library errors into the standard format.

---

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