# `Sigra.Plug.ErrorHandler`
[🔗](https://github.com/sztheory/sigra/blob/v1.20.0/lib/sigra/plug/error_handler.ex#L1)

Behaviour for handling authentication errors in the HTTP pipeline.

Implement this behaviour in your application to customize how authentication
errors are presented to users. The generated `MyAppWeb.AuthErrorHandler`
provides a default implementation.

## Error Types

  * `:unauthenticated` - No authenticated user found
  * `:stale_sudo` - Sudo window has expired, re-authentication required
  * `:rate_limited` - Request rate limit exceeded
  * `:insufficient_scope` - Bearer token lacks the required scope
  * `:token_expired` - API token has expired
  * `:token_revoked` - API token was revoked
  * `:mfa_required` - MFA enrollment or challenge required
  * `:no_active_org` - No active organization on the scope (Phase 14 / D-08);
    the current request requires an org context but `scope.active_organization`
    is nil. Typically reached when the user has zero memberships or the
    stale-pointer recovery path left the scope unpopulated.
  * `:insufficient_role` - Authenticated user's membership role is not in
    the required list for the requested resource (Phase 14 / D-08).

## Example

    defmodule MyAppWeb.AuthErrorHandler do
      @behaviour Sigra.Plug.ErrorHandler

      @impl true
      def auth_error(conn, :unauthenticated, _opts) do
        conn
        |> Phoenix.Controller.put_flash(:error, "You must log in to access this page.")
        |> Phoenix.Controller.redirect(to: "/login")
      end

      @impl true
      def auth_error(conn, :stale_sudo, _opts) do
        conn
        |> Phoenix.Controller.put_flash(:error, "Please re-enter your password to continue.")
        |> Phoenix.Controller.redirect(to: "/users/sudo")
      end

      @impl true
      def auth_error(conn, :rate_limited, _opts) do
        conn
        |> Plug.Conn.put_resp_content_type("text/plain")
        |> Plug.Conn.send_resp(429, "Too many requests. Please try again later.")
      end
    end

# `error_type`

```elixir
@type error_type() ::
  :unauthenticated
  | :stale_sudo
  | :rate_limited
  | :insufficient_scope
  | :token_expired
  | :token_revoked
  | :mfa_required
  | :no_active_org
  | :insufficient_role
  | :not_found
```

# `auth_error`
*since 0.1.0* 

```elixir
@callback auth_error(Plug.Conn.t(), error_type(), keyword()) :: Plug.Conn.t()
```

Handle an authentication error.

Called by `Sigra.Plug.RequireAuthenticated` and `Sigra.Plug.RequireSudo`
when authentication requirements are not met.

The `conn` has NOT been halted yet -- your implementation should send a
response. The calling plug will halt the connection after this callback returns.

---

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