# `Jido.AI.Error`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/error.ex#L1)

Splode-based error handling for Jido.AI.

Provides structured error types for AI operations including:
- API errors (rate limits, authentication, transient failures)
- Validation errors
- Runtime error envelope normalization and retryability policy

# `class`

```elixir
@type class() :: %{
  :__struct__ => class_module(),
  :__exception__ => true,
  :errors => [t()],
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}
```

# `class_module`

```elixir
@type class_module() ::
  Jido.AI.Error.Validation | Jido.AI.Error.API | Splode.Error.Unknown
```

# `error_class`

```elixir
@type error_class() :: :validation | :api | :unknown
```

# `error_envelope`

```elixir
@type error_envelope() :: %{
  type: atom(),
  message: String.t(),
  details: map(),
  retryable?: boolean()
}
```

# `t`

```elixir
@type t() :: %{
  :__struct__ => module(),
  :__exception__ => true,
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}
```

# `error_envelope`

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

Builds a normalized AI runtime error envelope.

The envelope is the package-owned caller-visible contract used by tool,
LLM, directive, and signal result paths.

# `normalize`

```elixir
@spec normalize(term(), atom(), String.t(), map()) :: error_envelope()
```

Normalizes arbitrary runtime error values into the canonical AI error envelope.

# `normalize_result`

```elixir
@spec normalize_result(term(), atom(), String.t()) ::
  {:ok, term(), [term()]} | {:error, error_envelope(), [term()]}
```

Ensures result payloads use `{:ok, term, effects}` or `{:error, reason, effects}` tuples.

# `retryable?`

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

Returns whether a result or error should be treated as retryable by runtime policy.

# `splode_error?`

# `to_map`

```elixir
@spec to_map(term()) :: error_envelope()
```

Serializes a runtime error term as the canonical AI runtime error map.

# `traverse_errors`

Traverses errors, calling `fun` for each leaf error, and returns a nested
map of results grouped by each error's `path`.

See `Splode.traverse_errors/2` for full documentation.

## Example

    iex> Elixir.Jido.AI.Error.traverse_errors(error, fn error ->
    ...>   Exception.message(error)
    ...> end)
    %{name: ["name is required"]}

# `unwrap!`

Raises an error if the result is an error, otherwise returns the result

Alternatively, you can use the `defsplode` macro, which does this automatically.

### Options

- `:error_opts` - Options to pass to `to_error/2` when converting the returned error
- `:unknown_error_opts` - Options to pass to the unknown error if the function returns only `:error`.
  not necessary if your function always returns `{:error, error}`.

### Examples

  def function(arg) do
    case do_something(arg) do
      :success -> :ok
      {:success, result} -> {:ok, result}
      {:error, error} -> {:error, error}
    end
  end

  def function!(arg) do
    YourErrors.unwrap!(function(arg))
  end

---

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