1. Design and error model

Start with an application vocabulary

A payment provider may fail with a timeout, a vendor-specific response, or an unexpected value. Your application needs a stable way to describe the failure without making every caller understand that provider.

RintoError lets an application define its own Error module and catalog. The catalog is the set of internal kinds that the application accepts. The library supplies construction, payload conversion, and exception formatting; the application owns the meaning of its errors.

defmodule MyApp.Error do
  use RintoError

  catalog do
    entry :payment_timeout, as: :payment_unavailable, http_status: 503
    entry :payment_rejected, as: :payment_unavailable, http_status: 502
    entry :reconciliation_failed
  end
end

Here, business code can distinguish :payment_timeout from :payment_rejected, while a client sees :payment_unavailable for both. An internal reconciliation error can exist without an HTTP status.

Keep three decisions separate

1. What happened? The stored kind belongs to the application's catalog.
2. What do we publish? as: optionally maps that kind to an output name. A payload contains only kind, data, and errors.
3. How does a transport respond? http_status: optionally supplies an HTTP status. Payload conversion also works for RPC, queues, and other consumers.

An output name is not automatically a constructable kind. Mapping happens once, and the status is looked up using the stored internal kind. This lets the application evolve its internal classifications while deliberately maintaining its public vocabulary.

Give each field a purpose

These are output boundaries, not automatic redaction. Anything you put in data or errors, or return from a source converter, may become public. Default exception text includes data, errors, and metadata as well as the kind and message.

Construct now, convert at the boundary

For a registered struct, build/1 translates the source into Error attributes. Later, the protocol function to_payload/2 translates the complete Error into public data and details, using its first argument only to select the source type. Both protocol functions must be implemented. Construction does not run conversion; a source used only for exceptions and logs may explicitly reject public output.

The original struct does not have to live in raw. The builder chooses what to retain. At output time, __source__ selects conversion; the type of raw does not.

The errors list is not an automatically traversed tree of business Errors. A source defines its own detail format. The library does not apply catalog aliases or recursively convert those details. The Ecto adapter, for example, produces field details with paths.

Choose policy in the application

RintoError does not choose your business kinds, turn every failure into HTTP 500, emit logs, or install a Phoenix error handler. Expected failures can travel as {:error, error}; the same Error is also an exception when raising is appropriate. Keep these decisions at the application boundary and use the catalog to make the shared vocabulary explicit.

中文 · Next: Define and use application errors