ZenWebsocket.ErrorHandler (ZenWebsocket v0.4.2)

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`

Summary

Types

explanation()

Human-readable error explanation with fix suggestions.

Functions

categorize_error(error)

Categorizes errors into recoverable vs non-recoverable types.

explain(error)

Returns a human-readable explanation for an error.

handle_error(error)

Handles errors by returning appropriate actions.

recoverable?(error)

Determines if an error is recoverable through reconnection.

Types

explanation()

@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)

Functions

categorize_error(error)

@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(error)

@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(error)

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

Handles errors by returning appropriate actions.

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

recoverable?(error)

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

Determines if an error is recoverable through reconnection.