# `Mojentic.Error`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.5.0/lib/mojentic/error.ex#L1)

Standardized error types and helpers for the Mojentic framework.

Follows Elixir conventions of returning `{:ok, result}` or `{:error, reason}` tuples.
Exceptions are reserved for truly exceptional situations.

## Error Reasons

### Atoms (simple errors)
- `:invalid_response` - Response from LLM gateway could not be parsed
- `:model_not_supported` - Requested model is not available
- `:timeout` - Operation timed out

### Tagged Tuples (errors with context)
- `{:gateway_error, message}` - LLM gateway error
- `{:api_error, message}` - API-specific error
- `{:http_error, status}` - HTTP request failed with status code
- `{:request_failed, reason}` - Network request failed
- `{:tool_error, message}` - Tool execution error
- `{:config_error, message}` - Invalid configuration
- `{:serialization_error, message}` - JSON serialization/deserialization error

# `error_reason`

```elixir
@type error_reason() :: simple_error() | tagged_error() | String.t()
```

# `result`

```elixir
@type result(success_type) :: {:ok, success_type} | {:error, error_reason()}
```

# `simple_error`

```elixir
@type simple_error() :: :invalid_response | :model_not_supported | :timeout
```

# `tagged_error`

```elixir
@type tagged_error() ::
  {:gateway_error, String.t()}
  | {:api_error, String.t()}
  | {:http_error, integer()}
  | {:request_failed, term()}
  | {:tool_error, String.t()}
  | {:config_error, String.t()}
  | {:serialization_error, String.t()}
```

# `api_error`

```elixir
@spec api_error(String.t()) :: {:error, {:api_error, String.t()}}
```

Creates an API error tuple.

## Examples

    iex> Mojentic.Error.api_error("Rate limit exceeded")
    {:error, {:api_error, "Rate limit exceeded"}}

# `config_error`

```elixir
@spec config_error(String.t()) :: {:error, {:config_error, String.t()}}
```

Creates a config error tuple.

## Examples

    iex> Mojentic.Error.config_error("Missing API key")
    {:error, {:config_error, "Missing API key"}}

# `format_error`

```elixir
@spec format_error(error_reason()) :: String.t()
```

Formats an error reason into a human-readable string.

## Examples

    iex> Mojentic.Error.format_error({:gateway_error, "Connection failed"})
    "Gateway error: Connection failed"

    iex> Mojentic.Error.format_error(:invalid_response)
    "Invalid response"

    iex> Mojentic.Error.format_error("Custom error")
    "Custom error"

# `gateway_error`

```elixir
@spec gateway_error(String.t()) :: {:error, {:gateway_error, String.t()}}
```

Creates a gateway error tuple.

## Examples

    iex> Mojentic.Error.gateway_error("Connection failed")
    {:error, {:gateway_error, "Connection failed"}}

# `http_error`

```elixir
@spec http_error(integer()) :: {:error, {:http_error, integer()}}
```

Creates an HTTP error tuple.

## Examples

    iex> Mojentic.Error.http_error(404)
    {:error, {:http_error, 404}}

# `invalid_response`

```elixir
@spec invalid_response() :: {:error, :invalid_response}
```

Creates an invalid response error tuple.

## Examples

    iex> Mojentic.Error.invalid_response()
    {:error, :invalid_response}

# `model_not_supported`

```elixir
@spec model_not_supported() :: {:error, :model_not_supported}
```

Creates a model not supported error tuple.

## Examples

    iex> Mojentic.Error.model_not_supported()
    {:error, :model_not_supported}

# `request_failed`

```elixir
@spec request_failed(term()) :: {:error, {:request_failed, term()}}
```

Creates a request failed error tuple.

## Examples

    iex> Mojentic.Error.request_failed(:timeout)
    {:error, {:request_failed, :timeout}}

# `serialization_error`

```elixir
@spec serialization_error(String.t()) :: {:error, {:serialization_error, String.t()}}
```

Creates a serialization error tuple.

## Examples

    iex> Mojentic.Error.serialization_error("Invalid JSON")
    {:error, {:serialization_error, "Invalid JSON"}}

# `timeout`

```elixir
@spec timeout() :: {:error, :timeout}
```

Creates a timeout error tuple.

## Examples

    iex> Mojentic.Error.timeout()
    {:error, :timeout}

# `tool_error`

```elixir
@spec tool_error(String.t()) :: {:error, {:tool_error, String.t()}}
```

Creates a tool error tuple.

## Examples

    iex> Mojentic.Error.tool_error("Invalid parameters")
    {:error, {:tool_error, "Invalid parameters"}}

---

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