SetuClient.Error (Setu Client v1.0.0)

Copy Markdown View Source

Structured error returned by every Setu SDK function.

All public functions return {:ok, result} or {:error, %SetuClient.Error{}}.

Error types

typeMeaning
:apiSetu returned a structured HTTP error response
:authHTTP 401 / 403 — bad or expired credentials
:rate_limitHTTP 429 — slow down; retry_after may be set
:networkTCP / DNS / TLS failure; always retryable
:validationClient-side check failed; no HTTP call was made
:decodeResponse body could not be decoded

Pattern matching

case SetuClient.Payments.UPI.create_dqr(cfg, merchant_id, params) do
  {:ok, qr} ->
    qr["intentLink"]

  {:error, %SetuClient.Error{type: :validation, field: f, message: m}} ->
    Logger.error("bad field #{f}: #{m}")

  {:error, %SetuClient.Error{type: :rate_limit, retry_after: ra}} ->
    backoff(ra)

  {:error, err} ->
    Logger.error(SetuClient.Error.message(err))
end

Summary

Types

error_type()
t()

Functions

api(status, code, message, trace_id \\ nil)

Builds an :api error from a non-2xx HTTP response.

auth(status, message, trace_id \\ nil)

Builds an :auth error for HTTP 401 / 403.

decode(message, cause \\ nil)

Builds a :decode error when JSON decoding fails.

message(err)

Returns a human-readable error message.

network(message, cause \\ nil)

Builds a :network error from a transport-level exception.

rate_limit(trace_id \\ nil, retry_after \\ nil)

Builds a :rate_limit error for HTTP 429.

retryable?(error)

Returns true when the error is safe to retry.

trace_id(error)

Returns the Setu trace ID, or nil if unavailable.

validation(field, message)

Builds a :validation error. No HTTP call is made when this is returned.

Types

error_type()

@type error_type() :: :api | :auth | :rate_limit | :network | :validation | :decode

t()

@type t() :: %SetuClient.Error{
  cause: term(),
  code: String.t() | nil,
  field: String.t() | nil,
  http_status: non_neg_integer() | nil,
  message: String.t(),
  retry_after: String.t() | nil,
  retryable: boolean(),
  trace_id: String.t() | nil,
  type: error_type()
}

Functions

api(status, code, message, trace_id \\ nil)

@spec api(non_neg_integer(), String.t(), String.t(), String.t() | nil) :: t()

Builds an :api error from a non-2xx HTTP response.

auth(status, message, trace_id \\ nil)

@spec auth(non_neg_integer(), String.t(), String.t() | nil) :: t()

Builds an :auth error for HTTP 401 / 403.

decode(message, cause \\ nil)

@spec decode(String.t(), term()) :: t()

Builds a :decode error when JSON decoding fails.

message(err)

@spec message(t()) :: String.t()

Returns a human-readable error message.

network(message, cause \\ nil)

@spec network(String.t(), term()) :: t()

Builds a :network error from a transport-level exception.

rate_limit(trace_id \\ nil, retry_after \\ nil)

@spec rate_limit(String.t() | nil, String.t() | nil) :: t()

Builds a :rate_limit error for HTTP 429.

retryable?(error)

@spec retryable?(t()) :: boolean()

Returns true when the error is safe to retry.

trace_id(error)

@spec trace_id(t()) :: String.t() | nil

Returns the Setu trace ID, or nil if unavailable.

validation(field, message)

@spec validation(String.t() | nil, String.t()) :: t()

Builds a :validation error. No HTTP call is made when this is returned.