# `Kagi.Error`
[🔗](https://github.com/rubas/kagi_ex/blob/v0.1.0/lib/kagi/error.ex#L1)

Structured error returned by every Kagi operation.

`Kagi.Error` is both a struct and an exception. Non-bang functions return it
in `{:error, error}`; bang functions raise it.

The `:reason` atom is stable for pattern matching; the `:message` string is
diagnostic text and may change between releases.

## Reasons

  * `:missing_session_token` - no valid session token is configured.
  * `:invalid_option` - an option failed client-side validation.
  * `:request_failed` - the HTTP request failed before receiving a response.
  * `:unauthorized` - Kagi returned HTTP 401 or 403.
  * `:rate_limited` - Kagi returned HTTP 429.
  * `:http_error` - Kagi returned an unexpected non-2xx status.
  * `:blocked` - Kagi returned a CAPTCHA or challenge page.
  * `:parse_error` - a response could not be parsed.

# `reason`

```elixir
@type reason() ::
  :missing_session_token
  | :invalid_option
  | :request_failed
  | :unauthorized
  | :rate_limited
  | :http_error
  | :blocked
  | :parse_error
```

Stable, machine-readable reason returned in `%Kagi.Error{}`.

# `t`

```elixir
@type t() :: %Kagi.Error{__exception__: true, message: String.t(), reason: reason()}
```

A `Kagi.Error` value.

# `new`

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

Builds a `Kagi.Error` with a stable reason and diagnostic message.

Application code usually receives these values from `Kagi` calls rather than
constructing them directly.

## Examples

    Kagi.Error.new(:invalid_option, "limit must be a non-negative integer")
    #=> %Kagi.Error{reason: :invalid_option, message: "limit must be a non-negative integer"}

---

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