# `ZenWebsocket.ErrorHandler`
[🔗](https://github.com/ZenHive/zen_websocket/blob/v0.4.2/lib/zen_websocket/error_handler.ex#L1)

Simple error handling for WebSocket connections.

Handles common error scenarios:
- Connection errors (network failures)
- Protocol errors (malformed frames)
- Authentication errors
- Timeout errors

Passes raw errors without wrapping to preserve original error information.
Provides human-readable explanations via `explain/1`.

## API Functions
| Function | Arity | Description | Param Kinds |
| --- | --- | --- | --- |
| `explain` | 1 | Get a human-readable explanation with fix suggestions for an error. | `error: value` |
| `handle_error` | 1 | Return the appropriate action for an error. | `error: value` |
| `recoverable?` | 1 | Check if an error is recoverable through reconnection. | `error: value` |
| `categorize_error` | 1 | Categorize an error as recoverable or fatal. | `error: value` |

# `explanation`

```elixir
@type explanation() :: %{
  message: String.t(),
  suggestion: String.t(),
  docs_url: String.t() | nil
}
```

Human-readable error explanation with fix suggestions.

- `message` - What went wrong
- `suggestion` - How to fix it
- `docs_url` - Link to relevant docs (nil unless overridden)

# `categorize_error`

```elixir
@spec categorize_error(term()) :: {:recoverable | :fatal, term()}
```

Categorizes errors into recoverable vs non-recoverable types.

Tags the error as `{:recoverable, error}` (network/transient) or
`{:fatal, error}` (protocol/auth) based on pattern matching.

# `explain`

```elixir
@spec explain(term()) :: explanation()
```

Returns a human-readable explanation for an error.

Provides a clear message describing what happened, a suggestion for how to
fix it, and optionally a documentation URL for more information.

## Examples

    iex> ZenWebsocket.ErrorHandler.explain({:error, :econnrefused})
    %{
      message: "Connection refused by server",
      suggestion: "Check that the server is running and verify the URL is correct",
      docs_url: nil
    }

    iex> ZenWebsocket.ErrorHandler.explain({:error, :unauthorized})
    %{
      message: "Authentication failed",
      suggestion: "Check your API credentials are valid and not expired",
      docs_url: nil
    }

# `handle_error`

```elixir
@spec handle_error(term()) :: :reconnect | :stop
```

Handles errors by returning appropriate actions.

Returns either :reconnect or :stop based on error recoverability.

# `recoverable?`

```elixir
@spec recoverable?(term()) :: boolean()
```

Determines if an error is recoverable through reconnection.

---

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