@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.

Rate limiting arrives as a two-element error, not a three-element one

This spec used to advertise {:error, :rate_limited, retry_after: seconds} as a third return shape. request/5 never returns it. Both rate-limit paths convert to a two-element error before returning, deliberately and for recorded reasons:

• a venue 429 becomes "Rate limited by the venue — retry after Ns", because a three-element tuple reaching a case written for two-element ones crashed 152 collector tasks in one night;
• our own limiter refusing becomes "Throttled by our own rate limiter (not the venue)", because the two used to share wording and a self-inflicted refusal was read as a flaky venue for weeks.

Both keep the retry interval in the message. The spec is corrected here rather than the behaviour: a spec that names a shape the function cannot return sends dialyzer after every caller that handles it, reporting correct code as unreachable — which is exactly what it did to the Gemini package's rate-limit clause. Found 2026-08-28.