clicksend 1.0.0 → 1.1.0

data/lib/clicksend/errors.rb

@@ -3,8 +3,79 @@
 require "time"
 
 module Clicksend
+  # What a failed (or successful) API call was: available as Error#request and
+  # Response#request. Safe to log: +path+ never includes the query string, and
+  # nothing here holds credentials, headers or bodies.
+  #
+  # +http_method+ is a lower-case Symbol (:get, :post, ...); +operation+ names the
+  # wrapped method that made the call (e.g. "sms.deliver"), or is whatever was
+  # passed to Client#request (nil by default); +attempts+ counts HTTP attempts,
+  # so it is 1 when nothing was retried.
+  RequestInfo = Data.define(:http_method, :path, :operation, :idempotent, :attempts) do
+    def to_s
+      "#{http_method.to_s.upcase} #{path}"
+    end
+
+    def inspect
+      "#<#{self.class.name} #{self} operation=#{operation.inspect} idempotent=#{idempotent} attempts=#{attempts}>"
+    end
+  end
+
   # Base class for every error raised by this gem.
-  class Error < StandardError; end
+  class Error < StandardError
+    # @return [Clicksend::RequestInfo, nil] the API call that failed, when the
+    #   error came from one
+    attr_reader :request
+
+    # @api private Set by the connection before the error is raised.
+    attr_writer :request
+
+    # Whether repeating the same request later is both safe (it cannot cause a
+    # second side effect, such as a second SMS) and might succeed.
+    #
+    # True for a 429, for connection failures that never reached ClickSend,
+    # and for connection failures and 5xx responses on idempotent requests.
+    # False for everything else, and always false when #ambiguous?.
+    def retryable?
+      false
+    end
+
+    # True when a request that is not safe to repeat (such as an SMS send) may
+    # or may not have been processed by ClickSend. Such errors are also
+    # Clicksend::AmbiguousRequestError, so they can be rescued as one.
+    def ambiguous?
+      is_a?(AmbiguousRequestError)
+    end
+
+    # @api private Marks this error as Clicksend::AmbiguousRequestError.
+    # (A +dup+ of the error is a fresh copy without the mark; +clone+ keeps it.)
+    def mark_ambiguous!
+      extend(AmbiguousRequestError)
+    end
+
+    # The message, followed by the request it came from, e.g.
+    # "HTTP 500 (POST /v3/sms/send)".
+    def to_s
+      request ? "#{super} (#{request})" : super
+    end
+  end
+
+  # Extended onto an error when a request that is not safe to repeat may have
+  # been processed: a timeout or connection failure after the request may have
+  # been written, a 5xx, an error reported inside a 2xx body, or a 2xx
+  # response that could not be read. The error keeps its class, so
+  #
+  #   rescue Clicksend::AmbiguousRequestError => e
+  #
+  # catches every unknown-outcome failure, and existing rescues of
+  # TimeoutError, ServerError, ... keep working.
+  #
+  # For an SMS send it means the message may or may not have been accepted.
+  # The gem never retries it; see the README on reconciling with
+  # Resources::SMS#history before sending again. Error#ambiguous? is the
+  # predicate.
+  module AmbiguousRequestError
+  end
 
   # Missing or invalid client configuration (e.g. no API key).
   class ConfigurationError < Error; end
@@ -24,6 +95,12 @@ module Clicksend
     def request_may_have_been_sent?
       @request_sent != false
     end
+
+    def retryable?
+      return false if ambiguous?
+
+      !request_may_have_been_sent? || request&.idempotent == true
+    end
   end
 
   # Opening the connection or reading the response took longer than the
@@ -58,6 +135,12 @@ module Clicksend
       @body = body
     end
 
+    # Rate-limit headers sent with this response, if any. See Clicksend::RateLimit.
+    # @return [Clicksend::RateLimit, nil]
+    def rate_limit
+      RateLimit.from_headers(headers)
+    end
+
     private
 
     def default_message(http_status, response_code, response_msg)
@@ -81,7 +164,9 @@ module Clicksend
   # 404: the resource does not exist.
   class NotFoundError < ClientError; end
 
-  # 429: rate limited. ClickSend did not process the request.
+  # 429: rate limited. ClickSend documents this as a request that "cannot be
+  # served", so it is treated as not processed (an inference, not a documented
+  # guarantee).
   class RateLimitError < ClientError
     # Seconds to wait before retrying, from the Retry-After header, if any.
     def retry_after
@@ -95,15 +180,26 @@ module Clicksend
           nil
         end
     end
+
+    def retryable?
+      !ambiguous?
+    end
   end
 
   # 5xx responses.
-  class ServerError < APIError; end
+  class ServerError < APIError
+    def retryable?
+      !ambiguous? && request&.idempotent == true
+    end
+  end
 
   # A single message sent with Clicksend::Resources::SMS#deliver was not
   # accepted (its per-message status was not "SUCCESS"), even though the HTTP
   # request itself succeeded. Batch sends never raise this; inspect
   # Clicksend::SMS::Batch#rejected instead.
+  #
+  # Not #retryable?: ClickSend decided. (A "THROTTLED" status means an identical
+  # message was sent to the same recipient moments ago.)
   class MessageRejected < Error
     # The Clicksend::SMS::Message describing the rejected message.
     attr_reader :result

data/lib/clicksend/instrumentation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Clicksend
+  # Instrumentation hooks. Pass any object that responds to
+  #
+  #   instrument(name, payload) { |payload| ... }
+  #
+  # as Client.new(instrumenter:). That is ActiveSupport::Notifications'
+  # signature, so a Rails application can pass ActiveSupport::Notifications
+  # itself and subscribe:
+  #
+  #   ActiveSupport::Notifications.subscribe("request.clicksend") do |event|
+  #     event.payload # => {http_method: :post, path: "/v3/sms/send", operation: "sms.deliver", ...}
+  #   end
+  #
+  # Events:
+  #
+  # [request.clicksend] Wraps one logical API call, retries included. The
+  #   payload has +:http_method+, +:path+, +:operation+ and +:idempotent+ when the
+  #   block starts; when it ends, +:attempts+, +:http_status+ (nil if no
+  #   response was received), +:response_code+ and +:ambiguous+ are added. If
+  #   the call raised, ActiveSupport adds +:exception+ / +:exception_object+.
+  # [retry.clicksend] Published (without a block) before each retry, with
+  #   +:http_method+, +:path+, +:operation+, +:attempt+ (1 for the first retry),
+  #   +:delay+ (seconds), +:error_class+ and +:http_status+.
+  #
+  # Payloads never contain credentials, headers, query strings, request or
+  # response bodies, phone numbers or message text. +path+ is the request path
+  # without its query string; for some endpoints it includes a message ID.
+  #
+  # The instrumenter is called on the caller's thread and must be thread-safe.
+  module Instrumentation
+    # The default: runs the block and publishes nothing.
+    module Null
+      module_function
+
+      def instrument(_name, payload = {})
+        yield payload if block_given?
+      end
+    end
+  end
+end

data/lib/clicksend/model.rb

@@ -32,6 +32,15 @@ module Clicksend
       end
     end
 
+    # An identifier or code that ClickSend sends as either a String or an
+    # Integer (e.g. list_id, history error_code) -> String
+    def code(value)
+      case value
+      when String then value
+      when Integer then value.to_s
+      end
+    end
+
     # Unix timestamp (Integer or numeric String) -> UTC Time
     def time(value)
       integer(value)&.then { |seconds| Time.at(seconds).utc }

data/lib/clicksend/page.rb

@@ -23,7 +23,7 @@ module Clicksend
     # @api private Use Client#paginate or a resource method.
     #
     # @yieldparam item [Hash] a raw item, to be converted into a model
-    def self.fetch(client, path, query: {}, page: nil, limit: nil, &build_item)
+    def self.fetch(client, path, query: {}, page: nil, limit: nil, operation: nil, &build_item)
       if page && !(page.is_a?(Integer) && page.positive?)
         raise ArgumentError, "page must be a positive Integer"
       end
@@ -32,9 +32,12 @@ module Clicksend
       end
 
       query = query.transform_keys(&:to_s)
-      response = client.request(:get, path, query: query.merge("page" => page, "limit" => limit).compact)
-      fetch_page = ->(number) { fetch(client, path, query: query, page: number, limit: limit, &build_item) }
+      response = client.request(:get, path, query: query.merge("page" => page, "limit" => limit).compact, operation: operation)
+      fetch_page = ->(number) { fetch(client, path, query: query, page: number, limit: limit, operation: operation, &build_item) }
       from_response(response, fetch_page, &build_item)
+    rescue MalformedResponseError => e
+      e.request ||= response&.request
+      raise
     end
 
     def self.from_response(response, fetch_page, &build_item)

data/lib/clicksend/rate_limit.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Clicksend
+  # Rate-limit counters ClickSend sent with a response, as exposed by
+  # Response#rate_limit and APIError#rate_limit.
+  #
+  # ClickSend does not document its rate limits or these headers. They were
+  # observed on GET /v3/account (2026-10-05): +x-ratelimit-limit+,
+  # +x-ratelimit-remaining+ and +ratelimit-reset+ (seconds until the window
+  # resets). Treat every field as advisory and possibly nil; nil overall means
+  # none of the headers were present.
+  #
+  # *Experimental*: because the headers are undocumented, this may change in
+  # a minor release if ClickSend changes them.
+  RateLimit = Data.define(:limit, :remaining, :reset_in)
+
+  class RateLimit
+    HEADERS = {
+      limit: "x-ratelimit-limit",
+      remaining: "x-ratelimit-remaining",
+      reset_in: "ratelimit-reset"
+    }.freeze
+
+    # @api private Use Response#rate_limit or APIError#rate_limit.
+    # @param headers [Hash] lower-cased response headers
+    # @return [Clicksend::RateLimit, nil]
+    def self.from_headers(headers)
+      return unless headers.is_a?(Hash)
+
+      values = HEADERS.transform_values { |name| non_negative_integer(headers[name]) }
+      new(**values) unless values.values.all?(&:nil?)
+    end
+
+    def self.non_negative_integer(value)
+      text = value.to_s.strip
+      Integer(text, 10) if text.match?(/\A\d{1,9}\z/)
+    end
+    private_class_method :non_negative_integer
+  end
+end

data/lib/clicksend/resources/account.rb

@@ -15,7 +15,7 @@ module Clicksend
       #
       # @return [Clicksend::Account]
       def fetch
-        Clicksend::Account.from_api(@client.request(:get, "/v3/account").data)
+        Clicksend::Account.from_api(@client.request(:get, "/v3/account", operation: "account.fetch").data)
       end
 
       def inspect

data/lib/clicksend/resources/sms.rb

@@ -11,6 +11,7 @@ module Clicksend
       ].freeze
       DEFAULT_FIELDS = (MESSAGE_FIELDS - %i[to list_id body]).freeze
       MESSAGE_ID = /\A[A-Za-z0-9-]+\z/
+      HISTORY_ORDERS = %i[asc desc].freeze
 
       def initialize(client)
         @client = client
@@ -26,9 +27,9 @@ module Clicksend
       # succeeded.
       #
       # Sends are never retried after a timeout or 5xx, because ClickSend has
-      # no idempotency key and the message may already have been accepted. A
-      # Clicksend::TimeoutError therefore means "unknown": reconcile using
-      # +custom_string+ before sending again.
+      # no idempotency key and the message may already have been accepted.
+      # Such failures are Clicksend::AmbiguousRequestError ("unknown"):
+      # reconcile with #history and your +custom_string+ before sending again.
       #
       # @param to [String] recipient in E.164 format, e.g. "+61411111111"
       # @param body [String] message text (Unicode is detected by ClickSend)
@@ -40,16 +41,20 @@ module Clicksend
       def deliver(to:, body:, from: nil, schedule: nil, custom_string: nil, country: nil, source: nil, from_email: nil, shorten_urls: nil)
         message = {to: to, body: body, from: from, schedule: schedule, custom_string: custom_string,
                    country: country, source: source, from_email: from_email}
-        batch = submit([normalize_message(message, nil)], shorten_urls)
+        batch, request = submit([normalize_message(message, nil)], shorten_urls, "sms.deliver")
         unless batch.messages.size == 1
-          raise MalformedResponseError.new(
+          raise ambiguous(MalformedResponseError.new(
             "Expected one message result, got #{batch.messages.size} (blocked_count: #{batch.blocked_count.inspect})",
             body: batch.raw
-          )
+          ), request)
         end
 
         result = batch.messages.first
-        raise MessageRejected, result if result.rejected?
+        if result.rejected?
+          rejected = MessageRejected.new(result)
+          rejected.request = request
+          raise rejected
+        end
 
         result
       end
@@ -87,7 +92,7 @@ module Clicksend
 
           normalize_message(defaults.merge(message.transform_keys(&:to_sym)), index)
         end
-        submit(normalized, shorten_urls)
+        submit(normalized, shorten_urls, "sms.deliver_batch").first
       end
 
       # Unread delivery receipts (GET /v3/sms/receipts).
@@ -101,21 +106,27 @@ module Clicksend
       #
       # @return [Clicksend::Page<Clicksend::SMS::Receipt>]
       def receipts(page: nil, limit: nil)
-        Page.fetch(@client, "/v3/sms/receipts", page: page, limit: limit) { |item| Clicksend::SMS::Receipt.from_api(item) }
+        Page.fetch(@client, "/v3/sms/receipts", page: page, limit: limit, operation: "sms.receipts") { |item| Clicksend::SMS::Receipt.from_api(item) }
       end
 
       # One delivery receipt, read or not (GET /v3/sms/receipts/{message_id}).
       # @return [Clicksend::SMS::Receipt]
       def receipt(message_id)
-        Clicksend::SMS::Receipt.from_api(@client.request(:get, "/v3/sms/receipts/#{message_id!(message_id)}").data)
+        Clicksend::SMS::Receipt.from_api(@client.request(:get, "/v3/sms/receipts/#{message_id!(message_id)}", operation: "sms.receipt").data)
       end
 
-      # Marks delivery receipts as read (PUT /v3/sms/receipts-read): all of
-      # them, or only those before +before+.
+      # Marks delivery receipts as read (PUT /v3/sms/receipts-read): only those
+      # before +before+, or, without it, every unread receipt at the moment
+      # ClickSend processes the call, including any that arrived after you
+      # last listed them. Prefer passing +before+.
+      #
+      # With +before+ the call is safe to repeat and is retried like a GET.
+      # Without it, it is not retried after a timeout or 5xx: a second "mark
+      # everything" could hide receipts that arrived in between.
       # @param before [Time, Integer, nil]
       # @return [nil]
       def mark_receipts_read(before: nil)
-        @client.request(:put, "/v3/sms/receipts-read", body: date_before(before), idempotent: true)
+        @client.request(:put, "/v3/sms/receipts-read", body: date_before(before), idempotent: !before.nil?, operation: "sms.mark_receipts_read")
         nil
       end
 
@@ -126,24 +137,71 @@ module Clicksend
       #
       # @return [Clicksend::Page<Clicksend::SMS::InboundMessage>]
       def inbound(page: nil, limit: nil)
-        Page.fetch(@client, "/v3/sms/inbound", page: page, limit: limit) { |item| Clicksend::SMS::InboundMessage.from_api(item) }
+        Page.fetch(@client, "/v3/sms/inbound", page: page, limit: limit, operation: "sms.inbound") { |item| Clicksend::SMS::InboundMessage.from_api(item) }
       end
 
-      # Marks inbound SMS as read (PUT /v3/sms/inbound-read): all of them, or
-      # only those before +before+.
+      # Marks inbound SMS as read (PUT /v3/sms/inbound-read): only those before
+      # +before+, or, without it, every unread inbound message at the moment
+      # ClickSend processes the call. Retried like #mark_receipts_read: only
+      # with +before+.
       # @return [nil]
       def mark_inbound_read(before: nil)
-        @client.request(:put, "/v3/sms/inbound-read", body: date_before(before), idempotent: true)
+        @client.request(:put, "/v3/sms/inbound-read", body: date_before(before), idempotent: !before.nil?, operation: "sms.mark_inbound_read")
         nil
       end
 
       # Marks one inbound SMS as read (PUT /v3/sms/inbound-read/{message_id}).
       # @return [nil]
       def mark_inbound_message_read(message_id)
-        @client.request(:put, "/v3/sms/inbound-read/#{message_id!(message_id)}", idempotent: true)
+        @client.request(:put, "/v3/sms/inbound-read/#{message_id!(message_id)}", idempotent: true, operation: "sms.mark_inbound_message_read")
         nil
       end
 
+      # Sent and received SMS (GET /v3/sms/history), as a Page of
+      # Clicksend::SMS::HistoryRecord, oldest first unless +order: :desc+.
+      #
+      #   client.sms.history(to: "+61411111111", date_from: 10.minutes.ago).auto_paging_each do |record|
+      #     record.custom_string
+      #   end
+      #
+      # For history ClickSend documents a single +q=field:value+ filter (its
+      # general search docs describe more, but not for this endpoint), so at
+      # most one of +to+, +from+, +status+ and +message_id+ may be given.
+      # +custom_string+ is not a documented filter: match on it yourself.
+      #
+      # This is the closest documented way to look for an ambiguous send (an
+      # AmbiguousRequestError from #deliver). ClickSend does not document how
+      # soon a sent message appears here, so a message missing from history is
+      # not proof that it was not sent.
+      #
+      # @param date_from [Time, Integer, nil] earliest send time
+      # @param date_to [Time, Integer, nil] latest send time
+      # @param status [String, nil] a history status such as "Failed"
+      # @param order [:asc, :desc] by date
+      # @return [Clicksend::Page<Clicksend::SMS::HistoryRecord>]
+      def history(date_from: nil, date_to: nil, to: nil, from: nil, status: nil, message_id: nil, order: :asc, page: nil, limit: nil)
+        filters = {to: to, from: from, status: status, message_id: message_id}.compact
+        if filters.size > 1
+          raise ArgumentError, "pass at most one of to:, from:, status: and message_id: (ClickSend documents a single q=field:value filter)"
+        end
+        filters.each do |name, value|
+          unless value.is_a?(String) && !value.empty? && value == value.strip && !value.match?(/[,:[:cntrl:]]/)
+            raise ArgumentError, "#{name} must be a non-empty String without commas, colons or surrounding spaces"
+          end
+        end
+        raise ArgumentError, "order must be :asc or :desc" unless HISTORY_ORDERS.include?(order)
+
+        query = {
+          "date_from" => (unix_time(date_from, "date_from") unless date_from.nil?),
+          "date_to" => (unix_time(date_to, "date_to") unless date_to.nil?),
+          "order_by" => "date:#{order}",
+          "q" => filters.first&.then { |name, value| "#{name}:#{value}" }
+        }.compact
+        Page.fetch(@client, "/v3/sms/history", query: query, page: page, limit: limit, operation: "sms.history") do |item|
+          Clicksend::SMS::HistoryRecord.from_api(item)
+        end
+      end
+
       def inspect
         "#<#{self.class.name}>"
       end
@@ -161,10 +219,30 @@ module Clicksend
         before.nil? ? {} : {date_before: unix_time(before, "before")}
       end
 
-      def submit(messages, shorten_urls)
+      # @return [Array(Clicksend::SMS::Batch, Clicksend::RequestInfo)]
+      def submit(messages, shorten_urls, operation)
         body = {messages: messages}
         body[:shorten_urls] = shorten_urls unless shorten_urls.nil?
-        Clicksend::SMS::Batch.from_api(@client.request(:post, "/v3/sms/send", body: body).data)
+        response = @client.request(:post, "/v3/sms/send", body: body, operation: operation)
+        begin
+          batch = Clicksend::SMS::Batch.from_api(response.data)
+          # Without a readable per-message status there is no telling a
+          # rejection from an accepted message. Reporting it as "rejected"
+          # could lead a caller to send it again.
+          unless batch.messages.all? { |message| message.status.is_a?(String) && !message.status.empty? }
+            raise MalformedResponseError.new("A message in the send result has no status", body: batch.raw)
+          end
+          [batch, response.request]
+        rescue MalformedResponseError => e
+          # ClickSend answered 2xx, so the messages may well have been queued.
+          raise ambiguous(e, response.request)
+        end
+      end
+
+      def ambiguous(error, request)
+        error.request ||= request
+        error.mark_ambiguous!
+        error
       end
 
       def normalize_message(message, index)

data/lib/clicksend/response.rb

@@ -9,7 +9,36 @@ module Clicksend
   #   {"http_code": 200, "response_code": "SUCCESS", "response_msg": "...", "data": {...}}
   #
   # The envelope readers return nil when the body doesn't follow that shape.
+  #
+  # #request (a Clicksend::RequestInfo) says which call this was and how many
+  # attempts it took. It is deliberately not a Data member, so equality,
+  # +to_h+ and pattern matching (+in [status, headers, body]+,
+  # +in {http_status:}+) behave exactly as in 1.0.
   Response = Data.define(:http_status, :headers, :body) do
+    def initialize(http_status:, headers:, body:, request: nil)
+      @request = request
+      super(http_status: http_status, headers: headers, body: body)
+    end
+
+    # @return [Clicksend::RequestInfo, nil]
+    attr_reader :request
+
+    # Like Data#with, keeping #request unless a new one is given.
+    def with(**changes)
+      super(request: request, **changes)
+    end
+
+    # Marshal (e.g. Rails.cache) must rebuild the object through #initialize:
+    # a frozen Data instance can't receive #request afterwards.
+    def _dump(_level)
+      Marshal.dump([to_h, request])
+    end
+
+    def self._load(data)
+      members, request = Marshal.load(data) # rubocop:disable Security/MarshalLoad
+      new(**members, request: request)
+    end
+
     # The envelope's +data+ member.
     def data
       envelope("data")
@@ -25,6 +54,12 @@ module Clicksend
       envelope("response_msg")
     end
 
+    # Rate-limit headers sent with this response, if any. See Clicksend::RateLimit.
+    # @return [Clicksend::RateLimit, nil]
+    def rate_limit
+      RateLimit.from_headers(headers)
+    end
+
     def inspect
       "#<#{self.class.name} http_status=#{http_status} response_code=#{response_code.inspect}>"
     end

data/lib/clicksend/retry_policy.rb

@@ -1,59 +1,76 @@
 # frozen_string_literal: true
 
 module Clicksend
-  # Decides whether a failed attempt may be retried, and after how long.
-  # @api private Configure it through Client.new(max_retries:).
+  # Decides how long to wait before retrying, and whether the retry budget
+  # allows another attempt. Pass one to Client.new(retry_policy:) to tune it:
   #
-  # ClickSend's send endpoints accept no idempotency key, so retrying a send
-  # that may already have reached ClickSend could deliver the message twice.
-  # The rules are therefore:
+  #   Clicksend::Client.new(retry_policy: Clicksend::RetryPolicy.new(max_retries: 4, max_retry_after: 10))
   #
-  # * 429 Too Many Requests: ClickSend did not process the request, so it is
-  #   retried for every method, honouring Retry-After (up to +max_retry_after+).
+  # It does not decide *whether a failure is safe to retry*. That rule is
+  # fixed in the connection, so no policy can make a send repeat after a
+  # failure that may already have reached ClickSend:
+  #
+  # * 429 Too Many Requests: retried for every method (ClickSend documents it
+  #   as a request that "cannot be served").
   # * Connection failures known to happen before the request was sent
   #   (refused, DNS, connect timeout): retried for every method.
-  # * Read timeouts, resets and 5xx responses: retried only when the request
-  #   is idempotent. By default only GET requests are.
+  # * Read timeouts, resets, TLS errors and 5xx responses: retried only when
+  #   the request is idempotent (GET, and mark-read calls with a cutoff).
+  # * Anything else, including an error reported inside a 2xx body: never.
+  #
+  # Only for failures in the first three groups is #delay asked. Any object
+  # with +max_retries+ and +delay(error:, attempt:)+ can stand in for this
+  # class; it must be thread-safe, as one client is shared across threads.
   class RetryPolicy
-    attr_reader :max_retries
+    attr_reader :max_retries, :base_delay, :max_delay, :max_retry_after
 
+    # @param max_retries [Integer] retries after the first attempt; 0 disables retrying
+    # @param base_delay [Numeric] seconds; backoff ceiling for the first retry
+    # @param max_delay [Numeric] seconds; the backoff ceiling never exceeds it
+    # @param max_retry_after [Numeric] longest Retry-After (seconds) worth
+    #   waiting for; a longer one is raised as RateLimitError instead of
+    #   blocking the caller
     def initialize(max_retries: 2, base_delay: 0.5, max_delay: 8.0, max_retry_after: 30, random: Random)
+      unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ConfigurationError, "max_retries must be a non-negative Integer"
+      end
+      {base_delay: base_delay, max_delay: max_delay, max_retry_after: max_retry_after}.each do |name, value|
+        raise ConfigurationError, "#{name} must be a non-negative number of seconds" unless value.is_a?(Numeric) && value >= 0
+      end
+
       @max_retries = max_retries
       @base_delay = base_delay
       @max_delay = max_delay
       @max_retry_after = max_retry_after
       @random = random
+      freeze
     end
 
-    # @param error [Clicksend::Error] the failure of attempt number +attempt+ (0-based)
+    # @param error [Clicksend::Error] the failure of attempt number +attempt+
+    #   (0-based); already known to be safe to retry
     # @return [Numeric, nil] seconds to wait before retrying, or nil to give up
-    def delay(error:, attempt:, idempotent:)
+    def delay(error:, attempt:, **)
       return if attempt >= max_retries
+      return backoff(attempt) unless error.is_a?(RateLimitError)
 
-      case error
-      when RateLimitError
-        rate_limit_delay(error, attempt)
-      when ServerError
-        backoff(attempt) if idempotent
-      when ConnectionError
-        backoff(attempt) if idempotent || !error.request_may_have_been_sent?
-      end
-    end
-
-    private
-
-    def rate_limit_delay(error, attempt)
       wait = error.retry_after
       return backoff(attempt) if wait.nil?
 
       # Rather than block a web request or job for minutes, surface the
       # RateLimitError and let the caller decide.
-      wait if wait <= @max_retry_after
+      wait if wait <= max_retry_after
     end
 
+    def inspect
+      "#<#{self.class.name} max_retries=#{max_retries} base_delay=#{base_delay} max_delay=#{max_delay} " \
+        "max_retry_after=#{max_retry_after}>"
+    end
+
+    private
+
     # Exponential backoff with "equal jitter": half fixed, half random.
     def backoff(attempt)
-      ceiling = [@base_delay * (2**attempt), @max_delay].min
+      ceiling = [base_delay * (2**attempt), max_delay].min
       (ceiling / 2.0) + (@random.rand * ceiling / 2.0)
     end
   end