The error umbrella.

Every failure this library reports is one of the structs in t/0. Before v0.4.0 there were ten different ad-hoc shapes — bare {status, body} tuples, {:unifi_error, msg}, {:unexpected_status, status, body}, raw Req structs — so a consumer could not write an exhaustive case, and every new shape was an invisible breaking change.

A handful of functions additionally return a documented plain atom for a non-error outcome that is not a controller failure (UnifiApi.Network.Sites.find_by_name/2 returns :not_found, UnifiApi.Auth.Cookie.logout/2 returns :not_logged_in). Those are named in the individual @specs rather than folded in here.

Exhaustive handling

case UnifiApi.Network.Clients.list(client, site_id) do
  {:ok, clients} -> {:ok, clients}
  {:error, %UnifiApi.AuthError{}} -> :reauth
  {:error, %UnifiApi.RateLimitError{retry_after: s}} -> {:backoff, s}
  {:error, %UnifiApi.ApiError{status: status}} -> {:api, status}
  {:error, %UnifiApi.TransportError{reason: reason}} -> {:transport, reason}
end

UnifiApi.StreamError only appears from the stream/* functions — as the {:error, reason, cursor} stream tail, or raised under raise_errors: true.