# `Image.Plug.Error`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/error.ex#L1)

Tagged error type returned by every public function in `Image.Plug`.

An error carries a stable `:tag` (an atom suitable for pattern matching
and for mapping to HTTP status codes), a human-readable `:message`,
and optional `:details` for diagnostic context.

Errors are returned as `{:error, %Image.Plug.Error{}}`. They are not
raised — `try/rescue` is reserved for true system boundaries per the
project's code style.

# `t`

```elixir
@type t() :: %Image.Plug.Error{details: map(), message: String.t(), tag: tag()}
```

# `tag`

```elixir
@type tag() ::
  :unknown_option
  | :invalid_option
  | :malformed_url
  | :variant_not_found
  | :variant_already_exists
  | :source_not_found
  | :source_fetch_error
  | :source_too_large
  | :unsupported_source_format
  | :unsupported_output_format
  | :unsupported_option
  | :output_too_large
  | :request_timeout
  | :pipeline_failed
  | :signature_required
  | :invalid_signature
  | :signature_expired
  | :not_implemented
  | :internal
```

A stable error tag. The set is open; callers should match the tags
documented for the function they call and treat unknown tags as `:internal`.

# `new`

```elixir
@spec new(tag(), String.t(), keyword()) :: t()
```

Builds an error struct.

### Arguments

* `tag` is an atom from `t:tag/0` describing the error class.

* `message` is a human-readable description of the failure.

### Options

* `:details` is a map of extra diagnostic context. Defaults to `%{}`.

### Returns

* An `Image.Plug.Error` struct.

### Examples

    iex> error = Image.Plug.Error.new(:unknown_option, "no such option", details: %{key: "wat"})
    iex> error.tag
    :unknown_option
    iex> error.details
    %{key: "wat"}

# `status`

```elixir
@spec status(t() | tag()) :: 100..599
```

Maps an error tag to a default HTTP status code.

### Arguments

* `error_or_tag` is either an `Image.Plug.Error` struct or an
  error tag atom.

### Returns

* An integer HTTP status code.

### Examples

    iex> Image.Plug.Error.status(:variant_not_found)
    404

    iex> Image.Plug.Error.status(Image.Plug.Error.new(:invalid_option, "bad"))
    400

    iex> Image.Plug.Error.status(:internal)
    500

---

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