Caravela.Error (Caravela v0.9.2)

Uniform error shape emitted by every Caravela read / write path.

Context functions and generated LiveViews can return any of four {:error, reason} shapes today:

{:error, :unauthorized}
{:error, :not_found}
{:error, %Ecto.Changeset{}}
{:error, other}

…and every handler has to match on all four. Caravela.Error collapses them into one struct so upstream code (a LiveView event handler, a JSON-API controller, a telemetry reporter) can pattern match once and discriminate by :kind:

case MyApp.Library.create_book(attrs, context) do
  {:ok, book} ->
    ...

  {:error, %Caravela.Error{kind: :unauthorized}} ->
    ...

  {:error, %Caravela.Error{kind: :invalid, details: changeset}} ->
    ...
end

Kinds

:unauthorized — a policy rule (scope, field, or allow) denied the request. details is the entity atom that failed the check.
:not_found — a get_* / delete_*(id, _) lookup returned nil (either missing or hidden by a policy scope). details is the id.
:invalid — input failed changeset validation. details is the %Ecto.Changeset{}.
:internal — anything else: a raised exception, a hook that returned a non-:ok tuple, a downstream integration failure. details is the original reason term.

The generated contexts continue to emit the plain atoms / changesets for backwards compatibility. Use wrap/1 to lift an existing error into the struct form when routing through a boundary that prefers the uniform shape.

Summary

Types

kind()

t()

Functions

message(error)

Short human-friendly string describing the error. Handy as a default flash message when a LiveView doesn't care about the discrimination.

wrap(err)

Lift a "plain" error reason into a %Caravela.Error{} struct.