@type auth_scheme() ::
  :hmac_sha256
  | :basic
  | :bearer
  | (http_method(), String.t(), body(), map() -> headers())

How to authenticate: one of the generic schemes, or a venue's own builder.

The function form is the hook that replaced a per-venue branch. The spec named only atom() for a while after the hook was added, so a venue passing a builder — the whole point of the hook — was told by dialyzer that the call "breaks the contract". Adding a capability without widening its spec makes the tool argue against the feature.

@type http_response() :: %{
  status: integer(),
  headers: headers() | map(),
  body: term()
}

A response as it comes back from the pipeline.

body is whatever the transport decoded, not a string. Req decodes JSON into a map or a list before this module sees it, and only leaves a binary when it could not.

It was declared String.t(), and that was not a harmless inaccuracy: dialyzer then concluded that any consumer matching a decoded body was matching something impossible, so every function reachable only through that branch was reported as unreachable dead code. A venue package's mix dialyzer failed with Function decimal/1 will never be called about a function called on every price it parses.

The application this pipeline came from hit the same class of problem from the other end and said so in a comment: a missing clause "poisoned dialyzer's success typing for every HttpClient.request/5 caller — the whole chain got narrowed to {:error, _} only." A wrong type is worse than a missing one; it makes the tool confidently wrong, and the reader believes it.

@type request_error() :: String.t() | {:exchange_error, provider(), term()}

Why a request did not produce a response.

Three shapes, and the spec used to name only the first — which made dialyzer tell every consumer that its handling of the other two was unreachable dead code.

• String.t() — a plain message, when no :provider was given.
• {:exchange_error, provider, reason} — the same message tagged with the venue, which is what a caller gets whenever it passes :provider, i.e. almost always.
• The rate-limit case is a three-element tuple, {:error, :rate_limited, retry_after: seconds}, not a two-element one. Unusual, and worth stating rather than leaving a caller to discover it from a CaseClauseError.