# `Snakepit.Error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L1)

Structured error type for Snakepit operations.

Provides detailed context for debugging cross-language and distributed system issues.
Python exceptions translated from the gRPC bridge are returned as
`Snakepit.Error.*` exception structs (see `Snakepit.Error.PythonException`).
`Snakepit.Error` remains the structured error type for Snakepit runtime failures.

## Error Categories

- `:worker` - Worker process errors (not found, crashed, etc.)
- `:timeout` - Operation timed out
- `:python_error` - Exception from Python code
- `:grpc_error` - gRPC communication error
- `:validation` - Input validation error
- `:pool` - Pool management error

## Examples

    # Create a worker error
    error = Snakepit.Error.worker_error("Worker not found", %{worker_id: "w1"})

    # Create a Python exception error
    error = Snakepit.Error.python_error(
      "ValueError",
      "Invalid input",
      traceback_string,
      %{function: "process_data"}
    )

    # Pattern match in your code
    case Snakepit.execute("command", %{}) do
      {:ok, result} -> result
      {:error, %Snakepit.Error{category: :timeout}} -> retry()
      {:error, %Snakepit.Error{category: :python_error} = error} ->
        Snakepit.Logger.error("Python error: #{error.message}")
        Snakepit.Logger.debug("Traceback: #{error.python_traceback}")
      {:error, error} -> {:error, error}
    end

# `category`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L43)

```elixir
@type category() ::
  :worker | :timeout | :python_error | :grpc_error | :validation | :pool
```

# `t`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L45)

```elixir
@type t() :: %Snakepit.Error{
  category: category(),
  details: map(),
  grpc_status: atom() | nil,
  message: String.t(),
  python_traceback: String.t() | nil
}
```

# `grpc_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L128)

```elixir
@spec grpc_error(atom(), String.t(), map()) :: t()
```

Creates a gRPC communication error.

## Examples

    iex> Snakepit.Error.grpc_error(:unavailable, "Service unavailable")
    %Snakepit.Error{
      category: :grpc_error,
      message: "Service unavailable",
      grpc_status: :unavailable
    }

# `pool_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L146)

```elixir
@spec pool_error(String.t(), map()) :: t()
```

Creates a pool management error.

## Examples

    iex> Snakepit.Error.pool_error("Pool not found", %{pool_name: :test})
    %Snakepit.Error{category: :pool, message: "Pool not found", details: %{pool_name: :test}}

# `python_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L106)

```elixir
@spec python_error(String.t(), String.t(), String.t(), map()) :: t()
```

Creates a Python exception error with traceback.

## Examples

    iex> Snakepit.Error.python_error("ValueError", "Invalid input", "Traceback...")
    %Snakepit.Error{
      category: :python_error,
      message: "ValueError: Invalid input",
      python_traceback: "Traceback...",
      details: %{exception_type: "ValueError"}
    }

# `timeout_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L84)

```elixir
@spec timeout_error(String.t(), map()) :: t()
```

Creates a timeout error.

## Examples

    iex> Snakepit.Error.timeout_error("Request timed out", %{timeout_ms: 5000})
    %Snakepit.Error{category: :timeout, message: "Request timed out", details: %{timeout_ms: 5000}}

# `validation_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L163)

```elixir
@spec validation_error(String.t(), map()) :: t()
```

Creates a validation error.

## Examples

    iex> Snakepit.Error.validation_error("Invalid field", %{field: "user_id"})
    %Snakepit.Error{category: :validation, message: "Invalid field", details: %{field: "user_id"}}

# `worker_error`
[🔗](https://github.com/nshkrdotcom/snakepit/blob/v0.11.1/lib/snakepit/error.ex#L67)

```elixir
@spec worker_error(String.t(), map()) :: t()
```

Creates a worker-related error.

## Examples

    iex> Snakepit.Error.worker_error("Worker crashed")
    %Snakepit.Error{category: :worker, message: "Worker crashed", details: %{}}

    iex> Snakepit.Error.worker_error("Worker not found", %{worker_id: "w1"})
    %Snakepit.Error{category: :worker, message: "Worker not found", details: %{worker_id: "w1"}}

---

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