# `Finitomata.Error`
[🔗](https://github.com/am-kantox/finitomata/blob/v0.41.0/lib/finitomata/error.ex#L1)

The canonical representation of a failure that happened while processing a transition.

Historically `Finitomata` stored the last error as an ad-hoc map and returned a handful
  of different error shapes (`{:error, atom}`, `{:error, tuple}`, keyword-tagged tuples
  like `{:error, transition: …, persistency: …}`.) This struct unifies them.

It is intentionally a **superset** of the legacy `%{state:, event:, error:}` map, so existing
  code that reads `last_error.error`, `last_error.state` or `last_error.event`, or pattern
  matches on `%{error: …}`, keeps working. New code should prefer the canonical fields:

- `stage` — where the failure originated (`:on_transition`, `:persistency`, …)
- `reason` — the normalized reason (the value unwrapped from a leading `{:error, _}`)
- `state`/`event`/`event_payload` — the transition context
- `error` — the raw value as it was produced (kept for backward compatibility)
- `context` — any extra information (e.g. the originating transition error for a
  persistency failure)

# `stage`
*since 0.36.0* 

```elixir
@type stage() :: :on_transition | :persistency | :not_allowed | :unknown
```

The stage of the FSM lifecycle the error originated from

# `t`
*since 0.36.0* 

```elixir
@type t() :: %Finitomata.Error{
  context: map(),
  error: any(),
  event: Finitomata.Transition.event() | nil,
  event_payload: Finitomata.event_payload() | nil,
  reason: any(),
  stage: stage(),
  state: Finitomata.Transition.state() | nil
}
```

# `wrap`
*since 0.36.0* 

```elixir
@spec wrap(
  any(),
  keyword()
) :: t()
```

Wraps an arbitrary transition failure into a canonical `t:Finitomata.Error.t/0`.

`context` is a keyword list providing the transition context (`:state`, `:event`,
  `:event_payload`). Already-wrapped errors are returned untouched.

---

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