# `A2UICore.Error`
[🔗](https://github.com/a2ui-elixir/a2ui/blob/v0.1.1/umbrella/apps/a2ui_core/lib/a2ui_core/error.ex#L1)

The single error struct used across the A2UI packages.

*Categories* classify errors for conformance matching and are drawn from
the reference implementation's exception classes:

| Category | Reference class |
|---|---|
| `:parse` | `A2uiParseError` |
| `:validation` | `A2uiValidationError` |
| `:catalog` | `A2uiCatalogError` |
| `:state` | `A2uiStateError` |
| `:integrity` | `A2uiIntegrityError` |
| `:recursion` | `A2uiRecursionError` |
| `:data` | `A2uiDataError` |
| `:expression` | `A2uiExpressionError` |
| `:rpc` | `A2uiRpcError` |
| `:compilation` | `A2uiCompilationError` (agent side) |

`A2UICore.Error` is usable both as a raised exception and inside
`{:error, error}` tuples; both forms are equivalent and the harness
decides which shape is used at the call site.

# `category`
*since 0.1.0* 

```elixir
@type category() ::
  :parse
  | :validation
  | :catalog
  | :state
  | :integrity
  | :recursion
  | :data
  | :expression
  | :rpc
  | :compilation
```

# `detail`
*since 0.1.0* 

```elixir
@type detail() :: %{path: String.t() | nil, code: String.t(), message: String.t()}
```

# `t`
*since 0.1.0* 

```elixir
@type t() :: %A2UICore.Error{
  __exception__: term(),
  category: category(),
  code: String.t(),
  details: [A2UICore.Error.Detail.t()],
  function_call_id: String.t() | nil,
  message: String.t(),
  path: String.t() | nil,
  surface_id: String.t() | nil
}
```

# `new`
*since 0.1.0* 

```elixir
@spec new(category(), String.t(), String.t(), keyword()) :: t()
```

Builds a new `A2UICore.Error` with the given `category` and `code`.

## Options

- `:path` — JSON pointer of the offending field.
- `:surface_id` — the surface the error pertains to.
- `:function_call_id` — relevant for v1.0 RPC failures.
- `:details` — list of `t:A2UICore.Error.Detail.t/0`.

## Examples

    iex> err = A2UICore.Error.new(:validation, "VALIDATION_FAILED", "bad")
    iex> {err.category, err.code}
    {:validation, "VALIDATION_FAILED"}

# `raise!`
*since 0.1.0* 

```elixir
@spec raise!(category(), String.t(), String.t(), keyword()) :: no_return()
```

Convenience raise helper — equivalent to
`raise A2UICore.Error, category:..., code:..., message:...`.

---

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