# `PhoenixKitEntities.Errors`
[🔗](https://github.com/BeamLabEU/phoenix_kit_entities/blob/v0.4.6/lib/phoenix_kit_entities/errors.ex#L1)

Central mapping from error atoms (returned by the Entities module's
public API) to translated human-readable strings.

Keeping the API layer locale-agnostic means callers can pattern-match
on atoms and decide their own presentation. Anything user-facing
(flash messages, error banners) goes through `message/1` which wraps
each mapping in `gettext/1` using this package's own
`PhoenixKitEntities.Gettext` backend.

## Supported reason shapes

  * plain atoms — `:cannot_remove_primary`, `:not_multilang`,
    `:entity_not_found`, etc.
  * tagged tuples — `{:invalid_field_type, type}`,
    `{:requires_options, type}`, `{:missing_required_keys, [keys]}`,
    `{:user_entity_limit_reached, max}`. The dynamic part is
    interpolated via `gettext` bindings so the wording lives in this
    package's own `.po` files.
  * strings — passed through unchanged (legacy / pre-existing
    messages already translated at the call site)
  * anything else — rendered as `"Unexpected error: <inspect>"` via
    gettext so nothing silently surfaces a raw struct

## Example

    iex> PhoenixKitEntities.Errors.message(:cannot_remove_primary)
    "Cannot remove the primary language."

    iex> PhoenixKitEntities.Errors.message({:invalid_field_type, "blob"})
    "Invalid field type: blob"

# `error_atom`

```elixir
@type error_atom() ::
  :cannot_remove_primary
  | :not_multilang
  | :entity_not_found
  | :not_found
  | :invalid_format
  | :unexpected
  | :already_trashed
  | :not_trashed
  | :referenced_by_external
  | :has_children
```

Plain atoms returned by the Entities public API.

# `tagged_error`

```elixir
@type tagged_error() ::
  {:invalid_field_type, String.t()}
  | {:requires_options, String.t()}
  | {:missing_required_keys, [String.t()]}
  | {:user_entity_limit_reached, non_neg_integer()}
```

Tagged tuples carrying interpolation context.

# `message`

```elixir
@spec message(term()) :: String.t()
```

Translates an error reason (atom, tagged tuple, or binary) into a
user-facing string via gettext.

---

*Consult [api-reference.md](api-reference.md) for complete listing*