OpenrouterSdk.Error (OpenRouter SDK v0.1.0)

uniform error struct returned by every public api function.

retryable? is the primary signal consumer middleware should use to decide whether to back off and try again (or rotate to a different model/provider). we keep body around so callers can inspect the raw upstream payload when they need to.

Summary

Types

kind()

t()

Functions

classify(status, body)

classify an http response (status + decoded body) into an error struct.

decode(body, reason)

build an error when a json body fails to decode

stream_disconnect(reason)

build an error for a stream that disconnected mid-flight

transport(reason)

build an error from a transport-layer failure (mint/finch reason term)

Types

kind()

@type kind() ::
  :transport
  | :timeout
  | :auth
  | :rate_limit
  | :payment_required
  | :invalid_request
  | :server
  | :stream_disconnect
  | :decode

t()

@type t() :: %OpenrouterSdk.Error{
  body: term(),
  code: String.t() | nil,
  kind: kind(),
  message: String.t(),
  retryable?: boolean(),
  status: non_neg_integer() | nil
}

Functions

classify(status, body)

@spec classify(non_neg_integer(), term()) :: t()

classify an http response (status + decoded body) into an error struct.

the status -> kind mapping follows the documented openrouter codes (400 invalid_request, 401 auth, 402 payment_required, 408 timeout, 429 rate_limit, 5xx server). retry semantics default to: transient on timeouts / rate limits / server errors, permanent on auth, billing, validation.

decode(body, reason)

@spec decode(binary(), term()) :: t()

build an error when a json body fails to decode

stream_disconnect(reason)

@spec stream_disconnect(term()) :: t()

build an error for a stream that disconnected mid-flight

transport(reason)

@spec transport(term()) :: t()

build an error from a transport-layer failure (mint/finch reason term)