Brings Errata's guards into scope and requires the module.

use Errata is the simplest way to set up a module that handles or creates Errata errors. It is exactly equivalent to importing just the three guards:

import Errata, only: [is_error: 1, is_domain_error: 1, is_infrastructure_error: 1]

This makes is_error/1, is_domain_error/1, and is_infrastructure_error/1 available unqualified — including in when clauses and function heads — and, because import implies require, also makes the create/2 and wrap/3 macros callable in their qualified form (Errata.create/2, Errata.wrap/3).

defmodule MyApp.Orders.Boundary do
  use Errata

  def handle({:error, e}) when is_error(e), do: handle_errata_error(e)
  def handle({:error, e}), do: handle_other_error(e)
end

Only the guards are imported. The rest of the Errata API stays qualified (Errata.to_map/1, Errata.put_context/3, Errata.report/2, and so on), which keeps generically named functions out of your module's namespace and reads clearly at a boundary.

Not the same as use Errata.Error

use Errata is for modules that work with errors. To define a new error type, use Errata.Error (or Errata.DomainError / Errata.InfrastructureError) instead.

@spec aggregate?(error()) :: boolean()

Returns true if error is an aggregate — a type declared with aggregate: true, which can hold member errors.

Note this is about the type, not the contents: an aggregate with no members is still an aggregate.

Raises an ArgumentError if error is not an Errata error.

@spec cause(error()) :: term() | nil

Returns the immediate cause wrapped by error, or nil if it has none.

The cause is the original error, exception, or value that was wrapped when the error was created (typically via the generated Errata.Error.wrap/2 macro, or by passing a :cause to Errata.Error.new/1 or Errata.Error.create/1). This returns the bare wrapped value; the captured stacktrace (if any) is held in the error's :cause field as an Errata.Cause struct.

iex> alias MyApp.Orders.OrderNotFound
iex> require OrderNotFound
iex> original = %RuntimeError{message: "boom"}
iex> error = OrderNotFound.wrap(original, reason: :lookup_failed)
iex> Errata.cause(error)
%RuntimeError{message: "boom"}

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.cause(OrderNotFound.new(reason: :not_found))
nil

Raises an ArgumentError if error is not an Errata error.

@spec code(error()) :: String.t() | nil

Returns the stable external code for error, or nil if it has none.

An error's type identity is its Elixir module, which is an implementation detail: renaming or moving the module changes the only identifier that to_map/1 exposes (error_type). That makes it a poor contract for external consumers — API clients, i18n catalogs, support tooling — who need an identifier that survives refactoring.

A code is that identifier. It is opt-in, and independent of the module name:

defmodule MyApp.Orders.OrderNotFound do
  use Errata.DomainError, code: "ORDER_NOT_FOUND"
end

The code appears in to_map/1 (and therefore in the JSON encoding) under the code key, and in the metadata emitted by log/2 and report/2. Types that do not declare one return nil, so a boundary that requires a code should supply its own fallback:

Errata.code(error) || "UNKNOWN"

Raises an ArgumentError if error is not an Errata error.

@spec context(error()) :: map()

Returns error's :context, or %{} if it has none.

Returns an empty map rather than nil for an error created without context, so calling code can treat the result as a map unconditionally.

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.context(OrderNotFound.new(context: %{order_id: 42}))
%{order_id: 42}

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.context(OrderNotFound.new())
%{}

This is the error's unredacted context — the values as captured. Redaction applies to what Errata serializes and emits (see Errata.Redaction); an error in your own hands keeps the real values for debugging, and this accessor reflects that.

Raises an ArgumentError if error is not an Errata error.

Creates an error of the given error_module, capturing the current __ENV__ and stacktrace into the :env field.

This is a convenience equivalent to the per-module Errata.Error.create/1 macro, but it lives on the Errata module. Because you typically already require Errata (to use the guards above), you can alias your error modules and call Errata.create/2 for any of them without a separate require for each error type:

defmodule MyApp.Orders do
  require Errata
  alias MyApp.Orders.{OrderNotFound, PaymentDeclined}

  def fetch_order(id) do
    {:error, Errata.create(OrderNotFound, reason: :not_found, context: %{order_id: id})}
  end
end

Compare to the per-module macro, which requires a require for every error type used in the module:

require MyApp.Orders.OrderNotFound, as: OrderNotFound
require MyApp.Orders.PaymentDeclined, as: PaymentDeclined

@spec display_message(error()) :: String.t() | nil

Returns the human-readable display message for an error: the value of its :message field, or nil if none was set.

This is distinct from Exception.message/1 (and the String.Chars implementation), which return a developer-oriented message that also includes the :reason — useful in logs and raised-exception output, but not intended for end users. Use display_message/1 when rendering an error for a user (for example, the body of a 4xx HTTP response), supplying your own fallback for the nil case.

This delegates to the error module's generated display_message/1 function, which returns the :message field unless the type overrides it. Override it to compute a user-facing message from the error's :reason or :context; the override applies here and in to_map/1 (and therefore the JSON encoding).

iex> alias MyApp.Orders.PaymentDeclined
iex> error = PaymentDeclined.new(reason: :insufficient_funds)
iex> Errata.display_message(error)
"the payment was declined"
iex> Exception.message(error)
"the payment was declined: :insufficient_funds"

Raises an ArgumentError if error is not an Errata error.

@spec errors(error()) :: [error()]

Returns the member errors of an aggregate, or [] for an ordinary error.

Returning [] rather than raising for a non-aggregate means calling code can treat every error uniformly — an ordinary error is simply an error with no members — instead of branching on aggregate?/1 first:

for member <- Errata.errors(error) do
  Logger.warning(Exception.message(member))
end

See Errata.Aggregate for how aggregates merge severity, retryability, and HTTP status across their members.

Raises an ArgumentError if error is not an Errata error.

@spec format_chain(error()) :: String.t()

Renders error and its full cause chain as a multi-line string for logging.

The head is the error's own developer-oriented message (as returned by Exception.message/1), followed by a Caused by: line for each wrapped cause. Wrapped Errata errors recurse into their own chain; other wrapped values are rendered via Exception.format/3, including the captured stacktrace when one is present.

Unlike Exception.message/1, which is kept clean and reports only the error's own message, this includes the entire chain — use it where you want the underlying context surfaced, such as a log entry.

Raises an ArgumentError if error is not an Errata error.

@spec from_map(module(), term(), keyword()) :: {:ok, error()} | {:error, term()}

Rebuilds an error of the given type from its encoded form.

This is the counterpart to to_map/1, for the receiving end of a boundary: a service that consumes an error another service serialized, a job runner reading a payload, a consumer taking a message off a queue. It accepts the map produced by to_map/1 directly, or the result of decoding that map's JSON (string keys are handled as well as atom keys).

iex> alias MyApp.Orders.OrderNotFound
iex> encoded = Errata.to_map(OrderNotFound.new(reason: :not_found))
iex> {:ok, error} = Errata.from_map(OrderNotFound, encoded)
iex> Errata.reason(error)
:not_found
iex> Errata.is_domain_error(error)
true

The error type is an argument rather than something read from the encoded error_type key. That key holds a module name, which is an implementation detail Errata deliberately does not treat as an identifier — resolving it would mean both trusting a name from the wire and keeping a registry of every error type, which is exactly what the structural is_error/1 guard avoids.

What comes back, and what does not

A decoded error is a faithful classification, not a faithful reconstruction:

• :reason, :message and :context are restored.
• :kind, http_status/1, severity/1 and retryable?/1 are recomputed from the type in this application, and the encoded values are ignored. The receiver's own definitions win, so an error decodes consistently with every locally-created error of the same type even if the sender is running an older version.
• :env is always nil. It describes a location in the sending process, which would be actively misleading attached to an error here.
• :cause is kept as the plain decoded value rather than being rebuilt into an error, since doing so would need its module too. Errata.cause/1 returns it; format_chain/1 still shows it.
• Context that was redacted on the way out stays redacted — the original values are not on the wire, and nothing here pretends otherwise.

Options

• :keys — what the keys of the decoded :context map should be. Defaults to :strings, which is the shape context arrives in from JSON. Pass :existing_atoms to convert keys that already exist as atoms, which makes a context built locally round-trip to the same shape:

  iex> alias MyApp.Orders.OrderNotFound
  iex> encoded = Errata.to_map(OrderNotFound.new(context: %{order_id: 42}))
  iex> {:ok, error} = Errata.from_map(OrderNotFound, encoded, keys: :existing_atoms)
  iex> Errata.context(error)
  %{order_id: 42}

  Conversion is best-effort and recursive: a key with no existing atom is left as a string rather than being created, so decoding untrusted input cannot exhaust the atom table. The default is :strings because :context holds arbitrary data, and that is where the risk would otherwise live.

  Both modes rewrite the keys, so the decoded shape depends only on this option — not on whether you passed JSON-decoded data or a map straight from to_map/1.

Errors

Returns {:error, reason} rather than raising, since malformed input is an expected condition where this is called. Passing something that is not an Errata error type is a programming error and still raises ArgumentError.

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.from_map(OrderNotFound, %{"reason" => "no_such_reason_exists"})
{:error, {:unknown_reason, "no_such_reason_exists"}}

A type that declares :reasons is decoded by matching against that declared set, so no atom is created from external input at all. See from_map!/3 for the raising variant.

@spec from_map!(module(), term(), keyword()) :: error()

Same as from_map/3, but returns the error directly and raises on failure.

iex> alias MyApp.Orders.OrderNotFound
iex> encoded = Errata.to_map(OrderNotFound.new(reason: :not_found))
iex> Errata.from_map!(OrderNotFound, encoded) |> Errata.reason()
:not_found

Reach for this when the encoded form comes from somewhere you control — your own job queue, a service you deploy alongside this one — and a malformed payload means something is broken rather than something a caller sent wrong. Use from_map/3 when the input is foreign and a bad payload is one of the outcomes you expect to handle.

Raises ArgumentError on anything from_map/3 would return {:error, _} for.

@spec http_status(error()) :: non_neg_integer()

Returns the HTTP status code associated with error.

This delegates to the error module's generated http_status/1 function, which defaults off the error's kind — :domain errors map to 422, :infrastructure errors to 503, and :general errors to 500. A specific status can be set per type with the :http_status option to use Errata.Error (and friends), or by overriding http_status/1 to compute a status from the error's :reason or :context.

This lets a boundary — such as a Phoenix fallback controller — map any Errata error to a response status without knowing its specific type:

def call(conn, {:error, error}) when Errata.is_error(error) do
  conn
  |> put_status(Errata.http_status(error))
  |> put_view(MyApp.ErrorView)
  |> render("error.json", error: error)
end

Raises an ArgumentError if error is not an Errata error.

Returns true if term is an Errata domain error type; otherwise returns false.

Allowed in guard tests.

Returns true if term is any Errata error type; otherwise returns false.

Allowed in guard tests.

Returns true if term is an Errata infrastructure error type; otherwise returns false.

Allowed in guard tests.

@spec kind(error()) :: error_kind()

Returns error's kind: :domain, :infrastructure, or :general.

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.kind(OrderNotFound.new())
:domain

For branching on the kind, the is_domain_error/1 and is_infrastructure_error/1 guards are usually the better tool, since they work in a guard clause. This is for the cases that want the value itself — logging it, or tagging a metric.

Raises an ArgumentError if error is not an Errata error.

@spec log(error(), Logger.level() | nil) :: :ok

Logs error at the given level with its structured fields attached as Logger metadata.

When no level is given, the error's own severity/1 is used (which is :error unless the error type sets a :severity).

The log message is the developer-oriented Exception.message/1 (combining :message and :reason). The error's :reason, :kind, :context, and origin :env are attached as Logger metadata rather than being flattened into the message string, so they remain queryable structured fields in backends that support them. The following metadata keys are set:

• :error_type — the error's module
• :kind — the error's kind (:domain / :infrastructure / :general)
• :reason — the error's reason
• :code — the error's stable external code, or nil (see code/1)
• :severity — the error's severity (see severity/1)
• :retryable — whether the error is retryable (see retryable?/1)
• :http_status — the error's HTTP status (see http_status/1)
• :context — the error's context map
• :env — a map of the origin module, function, file, and line

Returns :ok. Raises an ArgumentError if error is not an Errata error.

@spec merge_context(error(), map()) :: error()

Returns a copy of error with the key/value pairs from context merged into its :context map.

Like put_context/3, but merges an entire map at once. On key collisions, the values in the given context win (last-write-wins). If the error has no context yet (nil), it is initialized from context.

iex> alias MyApp.Orders.OrderNotFound
iex> error = OrderNotFound.new(reason: :not_found, context: %{order_id: 42})
iex> Errata.merge_context(error, %{user_id: 7, order_id: 99}).context
%{order_id: 99, user_id: 7}

Raises an ArgumentError if error is not an Errata error, or if context is not a map.

@spec put_context(error(), term(), term()) :: error()

Returns a copy of error with value stored under key in its :context map.

Context is normally set once, at the site where an error is created. But a structured error often travels up through several layers before reaching a boundary, and intermediate layers frequently know context that the creation site did not (the user_id known here, the request_id known there). Use put_context/3 (or merge_context/2) to enrich an error's context as it propagates, without rebuilding the struct by hand.

If the error has no context yet (nil), it is initialized to a map. An existing value under key is overwritten.

iex> alias MyApp.Orders.OrderNotFound
iex> error = OrderNotFound.new(reason: :not_found, context: %{order_id: 42})
iex> Errata.put_context(error, :user_id, 7).context
%{order_id: 42, user_id: 7}

A typical use is enriching an error as it propagates through a with chain:

with {:error, err} <- fetch_order(id) do
  {:error, Errata.put_context(err, :user_id, current_user_id)}
end

Raises an ArgumentError if error is not an Errata error.

@spec reason(error()) :: atom() | nil

Returns error's :reason, or nil if it has none.

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.reason(OrderNotFound.new(reason: :not_found))
:not_found

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.reason(OrderNotFound.new())
nil

Equivalent to reading error.reason, and preferable at a boundary that handles errors generically: a variable bound by a bare rescue e -> has no type the compiler can narrow, so e.reason there draws an "unknown key" warning — for any exception, not just an Errata one. Going through the accessor is a plain function call and warns for nothing.

Raises an ArgumentError if error is not an Errata error.

@spec report(
  error(),
  keyword()
) :: :ok

Emits a :telemetry event for error, and optionally logs it.

This is the seam for error reporting: rather than integrating with any particular external service, Errata emits a telemetry event that your application handles — attaching a handler that forwards to Sentry, a metrics backend, or wherever errors should go. The vendor integration stays in your application; Errata stays out of it.

The event is [:errata, :error], with:

• measurements %{system_time: integer(), count: 1} — :count is always 1, so Telemetry.Metrics.counter/2 works out of the box
• metadata containing the full :error struct plus :kind, :reason, :error_type, :code, :severity, :retryable, :http_status, and :context as top-level keys (simple values suitable for use as metric tags)

Options:

• :metadata — a map or keyword list of extra metadata merged into the event. The standard keys above are protected: on a key collision, the standard value wins.
• :measurements — extra measurements merged into the event, with the standard measurements likewise protected.
• :log — also log the error via log/2. false (the default) emits telemetry only; true logs at the error's own severity/1; an atom level (e.g. :warning) logs at that level.

Returns :ok. Raises an ArgumentError if error is not an Errata error.

:telemetry.attach("myapp-errata", [:errata, :error], &MyApp.ErrorReporter.handle/4, nil)

Errata.report(error, metadata: %{request_id: request_id}, log: :warning)

@spec retryable?(error()) :: boolean()

Returns true if error is considered retryable.

This delegates to the error module's generated retryable?/1 function, whose default is derived from the error's kind: :infrastructure errors are retryable (timeouts and connection blips are usually transient), while :domain and :general errors are not. Set it per type with the :retryable option to use Errata.Error (and friends), or override retryable?/1 to decide from the error's :reason or :context.

Errata deliberately provides no retry mechanism of its own — this is a classification that your retry logic, or a library such as ExternalService (which already uses Errata for its own errors), can branch on without knowing the error's specific type:

case do_work() do
  {:error, error} when Errata.is_error(error) ->
    if Errata.retryable?(error), do: retry(), else: {:error, error}

  result ->
    result
end

Raises an ArgumentError if error is not an Errata error.

@spec root_cause(error()) :: term()

Walks the cause chain of error and returns the deepest thing in it.

Deprecated

A cause chain is a chain of Errata errors, the deepest of which may carry a foreign original — the exception or value your code actually caught. This function is the one accessor that does not fit that model: it returns an Errata error or a foreign value depending on how the chain ends, so a caller has to work out which it got.

• root_error/1 gives you the deepest error, which always has a code, a context, a classification and a display_message/1.
• cause/1 on that error gives you the foreign original, or nil when there is none.
• format_chain/1 renders the whole chain, stacktraces included, for a log.

root_cause(error) is equivalent to cause(root_error(error)) || root_error(error).

Raises an ArgumentError if error is not an Errata error.

@spec root_error(error()) :: error()

Returns the deepest Errata error in error's cause chain.

A cause chain is Errata errors all the way down, optionally ending in one foreign value — a bare atom, an {:error, reason} tuple, a standard exception. root_cause/1 returns that bottom value whatever it is; this returns the deepest thing in the chain that is still an Errata error, and so still carries a code, a context, a classification and a display_message/1.

The two differ exactly when the chain bottoms out in a foreign value:

iex> alias MyApp.Http.RetriesExhausted
iex> require Errata
iex> error = Errata.wrap(RetriesExhausted, :econnrefused)
iex> Errata.root_error(error) == error
true
iex> Errata.root_error(error) |> Errata.cause()
:econnrefused

When the chain ends in an Errata error, they are the same value.

Reach for root_cause/1 to diagnose what failed — :econnrefused is the answer a developer wants in a log. Reach for this to render, report or classify, where a bare atom has nothing on it to use:

iex> alias MyApp.Http.RetriesExhausted
iex> require Errata
iex> Errata.wrap(RetriesExhausted, :econnrefused) |> Errata.root_error() |> Errata.code()
"RETRIES_EXHAUSTED"

Raises an ArgumentError if error is not an Errata error.

@spec severity(error()) :: Logger.level()

Returns the severity of error, as a Logger.level/0.

This delegates to the error module's generated severity/1 function, which is :error for every error type unless it says otherwise. Set a severity per type with the :severity option to use Errata.Error (and friends), or override severity/1 to compute one from the error's :reason or :context.

Severity is the level at which log/2 logs an error when no level is given explicitly, and is included in the metadata of both log/2 and report/2, so a telemetry handler can route or alert on it:

defmodule MyApp.Orders.RateLimited do
  use Errata.DomainError, severity: :warning
end

Unless a type opts in, the severity is :error:

iex> alias MyApp.Orders.OrderNotFound
iex> Errata.severity(OrderNotFound.new())
:error

Raises an ArgumentError if error is not an Errata error.

@spec to_error(
  term(),
  keyword()
) :: error()

Converts any value into an Errata error.

Errata errors are returned unchanged, which makes this safe to apply to a value that may already have been normalized:

iex> alias MyApp.Orders.OrderNotFound
iex> error = OrderNotFound.new(reason: :not_found)
iex> Errata.to_error(error) == error
true

Anything else is wrapped in an Errata.UnknownError, keeping the original as the cause. An atom also becomes the :reason:

iex> error = Errata.to_error(:timeout)
iex> error.__struct__
Errata.UnknownError
iex> Errata.reason(error)
:timeout
iex> Errata.cause(error)
:timeout

When to use this rather than wrap/3

Both turn an arbitrary value into an Errata error. The difference is whether you know what the failure means.

wrap/3 is an act of interpretation, used where a failure is caught: you name the error type because in that place you know what a dropped connection means for the operation in hand, and it always adds a layer because each layer's interpretation is worth keeping. to_error/2 is used where an error leaves the system and anything at all can arrive — there is no type to name, and an error that already is one comes back untouched.

That last part is the reason to keep them apart. Wrapping at a boundary replaces an already-correct classification with the wrapper's:

iex> require Errata
iex> error = MyApp.Orders.OrderNotFound.new(reason: :not_found)
iex> Errata.to_error(error) |> Errata.http_status()
422
iex> Errata.wrap(Errata.UnknownError, error) |> Errata.http_status()
500

It is also a plain function rather than a macro, so it can be captured and passed around (&Errata.to_error/1). The tradeoff is that it does not populate the :env field: normalization usually happens in a generic boundary function, where the call site is the boundary itself rather than anywhere informative about the failure.

Classifying the types you know

A 500 is the right answer for a genuinely unknown value and the wrong answer for an Ecto.Changeset, which is a 422, or a connection timeout, which is a retryable 503. This function classifies nothing on its own; it is the base case beneath the types your application recognizes:

defmodule MyApp.Errors do
  def to_error(%Ecto.Changeset{} = changeset),
    do: MyApp.ValidationFailed.new(reason: :invalid, cause: changeset)

  def to_error(other), do: Errata.to_error(other)
end

Keeping the recognized types in ordinary function clauses means a boundary reads one function to see how errors are classified, and that the classification can differ between boundaries where it needs to. See Errors at a boundary for the full pattern.

Options

• :fallback - the error type to wrap unrecognized values in; defaults to Errata.UnknownError. Useful when an application has a catch-all type of its own.
• :kind and :stacktrace - describe the wrapped cause, as in wrap/3.

Any remaining options are passed as error params (:reason, :message, :context), which is how a caller supplies a reason that the value itself does not carry:

iex> error = Errata.to_error("connection reset", reason: :disconnected)
iex> Errata.reason(error)
:disconnected

Handling {:error, reason} tuples

Tuples are not unwrapped: to_error({:error, :timeout}) normalizes the two-tuple itself, since a value that legitimately is a two-tuple is indistinguishable from one that means "error". Match the tuple at the call site instead:

case do_something() do
  {:ok, result} -> result
  {:error, reason} -> {:error, Errata.to_error(reason)}
end

Raises ArgumentError if :fallback is not an Errata error type.

@spec to_map(
  error(),
  keyword()
) :: map()

Converts any Errata error to a plain, JSON-encodable map.

This is the generic counterpart to the per-type Errata.Error.to_map/1 callback: it works on any value for which is_error/1 returns true, without needing to know the error's specific module. This is convenient at system boundaries (such as a Phoenix fallback controller) where errors of many different types are handled uniformly.

iex> alias MyApp.Orders.OrderNotFound
iex> error = OrderNotFound.new(reason: :not_found, context: %{order_id: 42})
iex> map = Errata.to_map(error)
iex> map.error_type
"MyApp.Orders.OrderNotFound"
iex> map.reason
:not_found
iex> map.context
%{order_id: 42}

The map contains :error_type, :code, :reason, :message (the display_message/1 rendering), :cause, :env, :context, and — for an aggregate type — :errors.

It also carries the error's classification, so that code holding only the serialized form can decide what to do with it:

iex> alias MyApp.Orders.OrderNotFound
iex> map = Errata.to_map(OrderNotFound.new(reason: :not_found))
iex> {map.kind, map.http_status, map.severity, map.retryable}
{:domain, 422, :error, false}

These four are computed through the same overridable functions as kind/1, http_status/1, severity/1 and retryable?/1, so an override is reflected here too. See Errors at a boundary.

Most consumers of this map need nothing else — the classification is enough to route, log and retry. An Elixir application that has the error type compiled can turn the map back into an error with from_map/3.

Raises an ArgumentError if error is not an Errata error.

Projecting the map

to_map/1 is the full record, aimed at an error reporter that wants everything. A response body crossing a boundary to a client wants much less — in particular it should not carry :env, which names a source file and line. Pass :only or :except (not both) to select:

Errata.to_map(error, except: [:env])
Errata.to_map(error, only: [:code, :message, :retryable])

The projection reaches aggregate members and a wrapped Errata cause as well, so except: [:env] removes every :env in the structure rather than only the outermost one. A cause that is a plain exception rather than an Errata error is left alone.

Keys are validated: a misspelled one raises rather than silently selecting nothing. See Errors at a boundary for which projection belongs on the wire and which belongs in your reporter.

Wraps cause in a new error of the given error_module, capturing the current __ENV__ and stacktrace into the :env field.

This is a convenience equivalent to the per-module Errata.Error.wrap/2 macro, but it lives on the Errata module. As with create/2, you typically already require Errata (for the guards above), so you can alias your error modules and call Errata.wrap/3 for any of them without a separate require for each error type:

defmodule MyApp.Orders do
  require Errata
  alias MyApp.Orders.OrderNotFound

  def fetch_order(id) do
    try do
      external_lookup!(id)
    rescue
      e ->
        {:error,
         Errata.wrap(OrderNotFound, e, stacktrace: __STACKTRACE__, reason: :lookup_failed)}
    end
  end
end

The original error, exception, or value is stored as the new error's :cause; retrieve it with Errata.cause/1 (or follow the chain with Errata.root_cause/1). The opts are the same as for the per-module Errata.Error.wrap/2 macro: the standard error params (:reason, :message, :context) plus :stacktrace and :kind, which describe the wrapped cause.

Wrapping is for when you know what a failure means — that is why it takes the error type as an argument, and why it always adds a layer even around an error that is already an Errata error. Where an error is on its way out of the system and anything at all can arrive, use to_error/2 instead: it has no type to name and leaves an already-classified error alone, where wrapping would replace that error's status and user-facing message with the wrapper's.