@type code() ::
  :CANCELLED
  | :UNKNOWN
  | :INVALID_ARGUMENT
  | :DEADLINE_EXCEEDED
  | :NOT_FOUND
  | :ALREADY_EXISTS
  | :PERMISSION_DENIED
  | :RESOURCE_EXHAUSTED
  | :FAILED_PRECONDITION
  | :ABORTED
  | :OUT_OF_RANGE
  | :UNIMPLEMENTED
  | :INTERNAL
  | :UNAVAILABLE
  | :DATA_LOSS
  | :UNAUTHENTICATED

The standard error code. See Google RPC error codes for more details.

@type debug_info() :: %{stack_entries: [String.t()], detail: String.t()}

Debug information for troubleshooting, including stack traces and details.

@type domain() :: String.t()

The error domain identifying the service or component that generated the error.

Examples: "com.myapp.payments", "com.stripe.api"

@type error_opt() ::
  {:metadata, metadata()}
  | {:causes, [t(module())]}
  | {:subject, subject() | nil}
  | {:debug_info, debug_info() | nil}
  | {:localized_message, localized_message() | nil}
  | {:retry_info, retry_info() | nil}
  | {:id, id() | nil}
  | {:time, time() | nil}
  | {:source_id, source_id() | nil}

Instance options for new!/1. See the type definition for available keys.

MyApp.NotFoundError.new!(
  metadata: Trogon.Error.Metadata.new(%{"user_id" => "123"}),
  subject: "user:123",
  localized_message: %{locale: "es", message: "Usuario no encontrado"}
)

@type help() :: %{links: [help_link()]}

Help information containing links to documentation or support resources.

@type help_link() :: %{description: String.t(), url: String.t()}

A single help link with a description and URL.

@type id() :: String.t()

Unique identifier for this error instance.

@type localized_message() :: %{locale: String.t(), message: String.t()}

Localized message for internationalization (i18n) support.

The locale follows IETF BCP-47 (e.g., "en-US", "fr-CH", "es-MX").

@type message() :: String.t()

The error message template describing what went wrong.

Defined at compile time and cannot be overridden at runtime. For dynamic values, treat the message as a template and pass runtime data via :metadata.

@type metadata() :: Trogon.Error.Metadata.t()

Instance-specific metadata as key-value pairs.

Trogon.Error.Metadata.new(%{
  "user_id" => "123",
  "resource_type" => "order"
})

See Trogon.Error.Metadata for visibility controls and advanced usage.

@type reason() :: String.t()

A unique identifier for the specific error within the domain.

Combined with domain/0, this creates a globally unique error identifier:

# domain: "com.myapp.payments", reason: "card_declined"
# domain: "com.myapp.users", reason: "not_found"

@type retry_info() :: retry_info_duration()

Retry information for recoverable errors, indicating when to retry.

retry_info: %{retry_offset: %Duration{second: 60}}

@type source_id() :: String.t()

Source identifier indicating where the error originated.

@type subject() :: String.t()

A pointer to the field or element that caused the error.

Examples: "email", "user.address.zipCode", "/items/0/quantity" (JSON Pointer)

@type t(struct) :: %{
  __struct__: struct,
  __exception__: true,
  specversion: non_neg_integer(),
  code: code(),
  message: message(),
  domain: domain(),
  reason: reason(),
  metadata: metadata(),
  causes: [t(module())],
  visibility: visibility(),
  subject: subject() | nil,
  id: id() | nil,
  time: time() | nil,
  help: help() | nil,
  debug_info: debug_info() | nil,
  localized_message: localized_message() | nil,
  retry_info: retry_info() | nil,
  source_id: source_id() | nil
}

The Trogon error struct type, parameterized by the error module.

@spec find_user(String.t()) ::
        {:ok, User.t()}
        | {:error, Trogon.Error.t(MyApp.NotFoundError)}

@type template_opt() ::
  {:domain, domain()}
  | {:reason, reason()}
  | {:message, atom() | message()}
  | {:metadata, Trogon.Error.Metadata.raw()}
  | {:code, code()}
  | {:visibility, visibility()}
  | {:help, help()}

A single template option for defining an error module with use Trogon.Error.

defmodule MyApp.NotFoundError do
  use Trogon.Error,
    domain: "com.myapp.resources",
    reason: "not_found",
    code: :NOT_FOUND,
    message: "Resource not found"
end

Options

• :domain (String.t/0) - Required. See domain/0.

• :reason (String.t/0) - Required. See reason/0.

• :message - See message/0. Use :code if not provided as a string.

• :metadata - Default metadata merged with instance metadata. See Trogon.Error.Metadata.raw/0. The default value is %{}.

• :code - See code/0. The default value is :UNKNOWN.

• :visibility - See visibility/0. The default value is :INTERNAL.

• :help (map/0) - See help/0.

  • :links (list of map/0)

@type time() :: DateTime.t()

Timestamp when the error occurred.

@type visibility() :: :INTERNAL | :PRIVATE | :PUBLIC

Whether the error should be visible to end users or kept internal.

• :INTERNAL - The error is not visible from outside the application.
• :PRIVATE - The error is visible from applications belonging to the same organization.
• :PUBLIC - The error is visible to everyone.