Ramp.Error exception (ramp v1.0.0)

Copy Markdown View Source

The structured exception raised/returned by every Ramp operation.

Every failure mode -- transport failures, HTTP error responses, deferred-task failures, webhook signature failures, timeouts -- is normalized into this one exception type so callers only need to pattern-match on :type instead of juggling several error shapes.

Fields

  • :type - one of type/0, classifying the failure.
  • :message - a human-readable description.
  • :status - the HTTP status code, if any.
  • :trace_id - the value of the x-trace-id response header, if present. Include this when contacting Ramp support.
  • :retry_after - seconds to wait before retrying, parsed from a 429 Too Many Requests response, if any.
  • :body - the raw response body, if any, for debugging.

Examples

case Ramp.Cards.get(client, "nonexistent") do
  {:ok, card} ->
    card

  {:error, %Ramp.Error{} = error} ->
    if Ramp.Error.not_found?(error) do
      :not_found
    else
      raise error
    end
end

Summary

Types

t()
type()

Functions

authentication_error?(arg1)

True if error represents an authentication (401) failure.

authorization_error?(arg1)

True if error represents an authorization (403) failure.

configuration_error(message)

Builds a configuration/validation error raised before any request is sent.

decode_error(reason)

Builds a JSON decode error.

deferred_task_error(task_id, reason)

Builds an error for a deferred task that finished with status ERROR.

from_response(status, raw_body, trace_id)

Builds a Ramp.Error from an HTTP response's status, body, and headers.

network_error(reason)

Builds a network-layer error (connection refused, DNS failure, etc.).

not_found?(arg1)

True if error represents an HTTP 404 / not-found condition.

rate_limited?(arg1)

True if error represents a 429 Too Many Requests response.

retryable?(arg1)

True if the underlying condition is generally safe to retry.

timeout_error(message)

Builds a client-side timeout error (deferred task or request timeout).

validation_error?(arg1)

True if error represents a request validation (400) failure.

webhook_error(message)

Builds a webhook signature verification error.

Types

t()

@type t() :: %Ramp.Error{
  __exception__: true,
  body: binary() | map() | nil,
  message: String.t(),
  retry_after: non_neg_integer() | nil,
  status: pos_integer() | nil,
  trace_id: String.t() | nil,
  type: type()
}

type()

@type type() ::
  :authentication_error
  | :authorization_error
  | :not_found
  | :validation_error
  | :rate_limit_error
  | :server_error
  | :timeout_error
  | :network_error
  | :deferred_task_error
  | :configuration_error
  | :webhook_verification_error
  | :decode_error
  | :unknown_error

Functions

authentication_error?(arg1)

@spec authentication_error?(t() | term()) :: boolean()

True if error represents an authentication (401) failure.

authorization_error?(arg1)

@spec authorization_error?(t() | term()) :: boolean()

True if error represents an authorization (403) failure.

configuration_error(message)

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

Builds a configuration/validation error raised before any request is sent.

decode_error(reason)

@spec decode_error(term()) :: t()

Builds a JSON decode error.

deferred_task_error(task_id, reason)

@spec deferred_task_error(String.t(), String.t()) :: t()

Builds an error for a deferred task that finished with status ERROR.

from_response(status, raw_body, trace_id)

@spec from_response(pos_integer(), binary(), String.t() | nil) :: t()

Builds a Ramp.Error from an HTTP response's status, body, and headers.

network_error(reason)

@spec network_error(term()) :: t()

Builds a network-layer error (connection refused, DNS failure, etc.).

not_found?(arg1)

@spec not_found?(t() | term()) :: boolean()

True if error represents an HTTP 404 / not-found condition.

rate_limited?(arg1)

@spec rate_limited?(t() | term()) :: boolean()

True if error represents a 429 Too Many Requests response.

retryable?(arg1)

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

True if the underlying condition is generally safe to retry.

Note: Ramp.HTTP already retries these automatically up to :max_retries times, so you normally never need this outside of your own custom retry logic (e.g. around Ramp.Poller.poll/3).

timeout_error(message)

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

Builds a client-side timeout error (deferred task or request timeout).

validation_error?(arg1)

@spec validation_error?(t() | term()) :: boolean()

True if error represents a request validation (400) failure.

webhook_error(message)

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

Builds a webhook signature verification error.