View Source Errata.UnknownError exception (Errata v1.9.0)

The error type that Errata.to_error/2 produces for values it does not recognize.

This is the only concrete error type Errata itself defines. It exists so that normalization is zero-configuration: an application (or a library built on Errata) can call Errata.to_error/1 without first having to declare a catch-all error type of its own.

It is an ordinary :general error, and so takes the defaults for that kind: HTTP status 500, severity :error, and not retryable. That is the honest classification for a value nothing knows anything about — if a more specific classification is possible, the value is not really unknown, and the way to say so is an Errata.Convertible implementation or the :fallback option.

iex> error = Errata.to_error(:enoent)
iex> error.__struct__
Errata.UnknownError
iex> Errata.http_status(error)
500
iex> Errata.retryable?(error)
false

The original value is preserved as the error's cause, so nothing is lost by normalizing:

iex> Errata.to_error(:enoent) |> Errata.cause()
:enoent

Applications that would rather see their own type at the end of the chain can pass one: Errata.to_error(value, fallback: MyApp.UnexpectedError).

Summary

Types

t()

Functions

code(error)

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

display_message(error)

Returns the user-facing display message for this error (the :message field by default).

http_status(error)

Returns the HTTP status code associated with this error (500 by default).

redact_context(error)

Returns this error's :context with sensitive values redacted (no keys declared).

retryable?(error)

Returns whether this error is considered retryable (false by default).

severity(error)

Returns the severity of this error (:error by default).

Types

t()

@type t() :: Errata.error()

Functions

code(error)

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

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

No code is set for this error type. Set one with the :code option, or override this function to derive a code from the error's :reason or :context. See also Errata.code/1.

display_message(error)

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

Returns the user-facing display message for this error (the :message field by default).

This is distinct from Exception.message/1, which also includes the error's :reason and is aimed at developers. Override this function to compute a message from the error's :reason or :context:

def display_message(%{context: %{order_id: id}}), do: "order #{id} does not exist"
def display_message(error), do: error.message

Errata.display_message/1 and Errata.to_map/1 both dispatch through this function, so an override applies to the JSON encoding and to anything rendering the error for a user. See also Errata.display_message/1.

http_status(error)

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

Returns the HTTP status code associated with this error (500 by default).

The default is derived from the error's kind, or set via the :http_status option. Override this function to compute a status from the error's :reason or :context. See also Errata.http_status/1.

redact_context(error)

@spec redact_context(Errata.error()) :: map()

Returns this error's :context with sensitive values redacted (no keys declared).

Called wherever Errata serializes the context — to_map/1 and the JSON encoding, Errata.log/2 metadata, and Errata.report/2 telemetry metadata. The error struct itself is left alone, so the real values remain available locally for debugging.

Declared keys are redacted recursively and match whether written as atoms or binaries. Set them with the :redact option, add a global floor with config :errata, redact: [...], or override this function for full control. See Errata.Redaction.

retryable?(error)

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

Returns whether this error is considered retryable (false by default).

The default is derived from the error's kind — :infrastructure errors are retryable, :domain and :general errors are not — or set via the :retryable option. Override this function to decide from the error's :reason or :context. See also Errata.retryable?/1.

severity(error)

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

Returns the severity of this error (:error by default).

The severity is a Logger.level/0 and is the level at which Errata.log/2 logs the error when no level is given explicitly. Set it with the :severity option, or override this function to compute a severity from the error's :reason or :context. See also Errata.severity/1.