clicksend 1.0.0 → 1.1.0

data/docs/clicksend-api-notes.md

@@ -1,14 +1,19 @@
 # ClickSend API notes
 
 How this gem interprets ClickSend's REST v3 documentation, where that documentation is
-ambiguous, and what the live API actually did. Last reviewed 2026-10-05, including live runs
-that covered sending but did not observe a delivery receipt (see "Live verification").
+ambiguous, and what the live API actually did. Last reviewed 2026-10-06: the documentation
+review covered all 34 OpenAPI sections, and the live runs on 2026-10-05 and 2026-10-06 (see
+"Live verification") covered sending and read-only history and rate-limit checks, but no
+delivery receipt.
 
 Sources:
 - [API reference](https://developers.clicksend.com/docs/), with its OpenAPI files at
   `https://developers.clicksend.com/docs/_spec/<section>.yaml`
 - [Testing](https://developers.clicksend.com/docs/testing)
 - [SMS error codes](https://help.clicksend.com/en/articles/42318-sms-error-codes)
+- Superseded but still informative: the [legacy HTTP v2 docs](https://developers.clicksend.com/docs/http/v2/)
+  and the [archived REST v3 docs](https://web.archive.org/web/20220502204655/https://developers.clicksend.com/docs/rest/v3/)
+  (2022), the only sources that list the fields ClickSend pushes to webhook URLs
 
 ## Behaviour taken from the documentation
 
@@ -20,13 +25,19 @@ Sources:
 | Per-message status | `/sms/send` `http_code` "doesn't reflect the status of each message" | `MessageRejected` (single) / `Batch#rejected` |
 | Pagination | `page` (default 1) and `limit` (default 15, min 15, max 100); `total`, `per_page`, `current_page`, `last_page` | `Page`; `limit` checked against 15..100 |
 | Receipt status codes | 200 sent/queued, 201 delivered, 300 temporary failure (ClickSend retries), 301 failed | `pending?` / `delivered?` / `failed?` |
-| Unread-only lists | Receipts and inbound marked read "won't be shown" in the list endpoints | Documented in the README (paging pitfall) |
+| Unread-only lists | Receipts and inbound marked read "won't be shown" in the list endpoints. Listing does not mark anything read (archived docs) | Documented in the README (paging pitfall) |
 | POLL rules | Polling receipts and inbound requires a rule with the POLL action | Documented |
-| Mark-read cutoff | `date_before`, Unix timestamp, optional | `before:` (Time or Integer); `{}` when omitted, which matches the request schema |
-| Unicode | Detected automatically; no `messagetype` in v3 | Not exposed |
+| Mark-read cutoff | `date_before`, Unix timestamp, optional. Without it, **everything** is marked read ("mark all", and the archived "If not given, all messages will be marked as read") | `before:` (Time or Integer); `{}` when omitted. Since 1.1 retried only with a cutoff (see "Retry safety") |
+| Per-receipt mark-read | None: receipts can only be marked read by cutoff. Inbound messages have `PUT /v3/sms/inbound-read/{message_id}` | `mark_inbound_message_read` only |
+| Unicode | Detected automatically **if** the account's dashboard setting is "Autodetect" (help 42194); no `messagetype` in v3 | Not exposed |
 | URLs in SMS | Paused for new customers pending approval | Documented |
-| Test numbers | e.g. `+61411111111`: "No messages will be sent, and your account won't be charged" | Used by the live specs. **Live:** still subject to the account's enabled countries (see below) |
-| Idempotency | No idempotency key on any send operation | Sends are never retried after timeouts or 5xx |
+| Test numbers | e.g. `+61411111111`: "No messages will be sent, and your account won't be charged". The legacy v2 docs add: "A delivery report won't be generated when using a test number" | Used by the live specs. **Live:** still subject to the account's enabled countries, and no receipt (see below) |
+| Idempotency | No idempotency key on any operation (all 34 sections searched) | Sends are never retried after timeouts or 5xx |
+| `THROTTLED` | Application code: "Identical message body recently sent to the same recipient." Window and placement undocumented | Treated as an ordinary rejection; never relied on for deduplication |
+| History search | `GET /v3/sms/history`: `date_from`, `date_to`, `order_by` (`date:asc` default), `page`, `limit`, and `q=field:value` for `status`, `to`, `from`, `subaccount_id`, `message_id`. `custom_string` is **not** a filter | `sms.history` takes one of `to:`, `from:`, `status:`, `message_id:`; match `custom_string` yourself |
+| Webhooks (push) | Automation rules with the `URL` action. Inbound rules: `webhook_type` `post` (form, default), `get` or `json` (format unspecified). Receipts: form-encoded POST according to the archived v3 docs (help 42270 covers inbound rules only). **No payload schema** in the current docs; the archived docs list the fields, matching the poll schemas plus `user_id` and (receipts) `status`. Archived: a non-200 is retried every 10 minutes, 10 times | `Clicksend::Webhook` parses into `SMS::Receipt` / `SMS::InboundMessage` |
+| Webhook authentication | **None documented.** No signature, HMAC or shared secret in any current, archived or help source. Current docs list no source IP addresses; archived help pages (around 2019–2021, no longer published) listed six and said pushes come from a fixed pool | No verification method and no IP allowlisting; README prescribes a secret URL and confirming via the API |
+| Request ID | None documented; no spec declares any response header | `Error#request` describes the call instead |
 
 ## Ambiguities and inconsistencies
 
@@ -51,14 +62,15 @@ These were found by the contract specs (`bundle exec rake contract`), which pin
    until this is verified; use `client.request`.
 8. **Inbound mark-read example.** The request example sends `date_before` as a string
    (`"1961900166"`); the schema says integer. The gem sends an integer.
-9. **Batch size.** "Up to 1000 messages" appears only in a code-sample comment, not in the schema.
-   Not enforced.
+9. **Batch size.** "Up to 1000 messages" appears in a code-sample comment and in the archived 2022
+   docs, not in the current schema. Not enforced.
 10. **Blocked messages.** `blocked_count` is documented, but not whether blocked messages also
     appear in `messages[]`. **Live: they do** (a `COUNTRY_NOT_ENABLED` message was listed and
     counted in `blocked_count`). `Batch#all_queued?` checks both.
-11. **Rate limits.** 429 is documented, but the referenced "Rate Limiting" section doesn't exist.
-    See the live results below for what the API actually sends. The gem honours `Retry-After`
-    and doesn't depend on the other headers.
+11. **Rate limits.** 429 is documented, but the referenced "Rate Limiting" section doesn't exist
+    (nor in the 2022 archive). See the live results below for what the API actually sends. The
+    gem honours `Retry-After`, and since 1.1 exposes the other observed headers as
+    `Response#rate_limit` / `APIError#rate_limit`, without depending on them.
 12. **Error HTTP statuses.** The docs list application codes such as `INVALID_RECIPIENT` and
     `INSUFFICIENT_CREDIT` but not which HTTP status accompanies them. **Live:** on `/sms/send`,
     `INVALID_RECIPIENT` and `COUNTRY_NOT_ENABLED` are per-message statuses inside an HTTP 200, not
@@ -67,6 +79,12 @@ These were found by the contract specs (`bundle exec rake contract`), which pin
     live response, include `_subaccount.api_key`. `Account#raw` replaces that value with
     `"[REDACTED]"`. The escape hatch returns bodies verbatim, so `client.request(:get,
     "/v3/account").body` contains the key and must not be logged.
+14. **History example.** The `view-sms-history` example uses `status: 200` instead of `http_code` and
+    omits the pagination wrapper the schema declares. **Live: the schema is right** (paginated
+    envelope). History `status_code` is documented as a string; live it was `null` for a
+    test-number message.
+15. **Help links.** The receipt and inbound-URL help links inside `sms.yaml` now redirect to
+    unrelated articles.
 
 ## Defensive behaviour (not documented for v3)
 
@@ -120,6 +138,13 @@ account. This was the only send in the run, and retries were off.
 Receipt retrieval and parsing are therefore verified against ClickSend's published examples and
 the contract specs only, **not** against a live receipt.
 
+### Read-only checks (2026-10-06)
+
+| Behaviour | Live result |
+|---|---|
+| `GET /v3/sms/history?q=to:%2B61411111111&date_from=…&order_by=date:asc&limit=100` (`sms.history(to:, date_from:)`) | HTTP 200, paginated envelope. Exactly one row, the accepted test-number message from 2026-10-05, so `q=to:` filters and the encoded `+` works. Row: `direction: "out"`, `status: "Completed"`, `status_code: null`, `status_text: null`, `message_parts: 0`, `message_price: "0.0000"`, `custom_string` a String, `date` an Integer, `schedule` a String. The documented fields, plus `contact_id`, `user_id`, `subaccount_id`, `first_name`, `last_name`, `_api_username` |
+| `GET /v3/account` rate-limit headers through `Response#rate_limit` | `limit: 20`, `remaining` and `reset_in` Integers |
+
 ### Still unverified
 
 These need a receipt for a real (non-test) message, existing inbound messages, or the public
@@ -129,8 +154,12 @@ test accounts:
 - [ ] Inbound timestamp field (`timestamp` or `timestamp_send`); no inbound messages existed
 - [ ] HTTP status and `response_code` for the `nocredit`, `notactive` and `banned` test accounts
 - [ ] Whether mark-read accepts an empty `{}` body. Deliberately not tested, because it would
-      mark every unread item read. The gem sends `{}` when `before:` is omitted; the request
-      schema allows it.
+      mark every unread item read (documented). The gem sends `{}` when `before:` is omitted; the
+      request schema allows it.
+- [ ] A real webhook push: its content type, field names and types. Field names come from the
+      poll schemas and the archived docs
+- [ ] How soon a sent message appears in history, and whether `date_from`/`date_to` are inclusive
+- [ ] Where and when `THROTTLED` is returned
 - [ ] Rate limits for endpoints other than `GET /v3/account`
 
 ## Retry safety: the rules and why
@@ -143,12 +172,19 @@ knows the first attempt did not reach ClickSend, or that ClickSend did not act o
 | 429 | ClickSend documents it as "a request cannot be served due to the application's rate limit". Inferred, not documented: the observed body (`"Too many attempts."`) looks like a throttling layer's response, produced before the request is handled | every method, honouring `Retry-After` up to 30s |
 | Connection refused, DNS failure, connect timeout (`Net::OpenTimeout`) | These can only happen before the request is written | every method |
 | Read timeout, connection reset, broken pipe, unreachable host mid-request | The request may have been written and processed | idempotent requests only |
+| Mark-read **without** a cutoff | "Mark everything read" is evaluated when ClickSend processes it, so a repeat can hide items that arrived in between | never (since 1.1); with a cutoff it is idempotent |
 | TLS errors | Usually a handshake failure (not sent), but `OpenSSL::SSL::SSLError` also covers failures after the request was written | idempotent requests only |
 | 5xx | ClickSend may have acted before failing | idempotent requests only |
 | Error reported only inside a 2xx body | Undocumented | never |
 
-"Idempotent" means `GET`, plus the gem's mark-read calls. `client.request` assumes only `GET`,
-because ClickSend uses `POST` and `PUT` for sends, purchases and credit transfers.
+"Idempotent" means `GET`, the mark-read calls that have a cutoff, and marking one inbound message
+read. `client.request` assumes only `GET`, because ClickSend uses `POST` and `PUT` for sends,
+purchases and credit transfers.
+
+Since 1.1 this rule lives in the connection and cannot be changed by configuration: a custom
+`retry_policy` only chooses delays and the retry budget. When a non-idempotent request fails in
+a way that may have been processed (a row above marked "idempotent requests only" or "never", or
+a 2xx answer the gem cannot read), the error is extended with `Clicksend::AmbiguousRequestError`.
 
 Underneath the gem there are no hidden retries. `Net::HTTP` retries `GET`/`PUT`/`DELETE`
 itself unless `max_retries` is 0, and faraday-net_http sets it to 0.

data/lib/clicksend/client.rb

@@ -18,7 +18,13 @@ module Clicksend
     DEFAULT_MAX_RETRIES = 2
     LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
 
-    attr_reader :username, :base_url, :timeout, :open_timeout, :max_retries
+    attr_reader :username, :base_url, :timeout, :open_timeout
+
+    # @return [#delay, #max_retries] see Clicksend::RetryPolicy
+    attr_reader :retry_policy
+
+    # @return [#instrument] see Clicksend::Instrumentation
+    attr_reader :instrumenter
 
     # @return [Clicksend::Resources::Account]
     attr_reader :account
@@ -33,21 +39,29 @@ module Clicksend
     # @param timeout [Numeric] seconds to wait for a response (read timeout)
     # @param open_timeout [Numeric] seconds to wait for the TCP/TLS connection
     # @param max_retries [Integer] retries for failures that are safe to retry
-    #   (see Clicksend::RetryPolicy); 0 disables retries
+    #   (see Clicksend::RetryPolicy); 0 disables retries. Default 2. A shortcut
+    #   for +retry_policy: RetryPolicy.new(max_retries: n)+; pass one or the other.
+    # @param retry_policy [#delay, #max_retries] backoff timing and retry budget
+    #   (see Clicksend::RetryPolicy). Which failures are retried at all is not
+    #   configurable.
     # @param logger [#info, #warn, nil] receives one line per HTTP attempt;
     #   never request/response bodies, query strings or credentials
+    # @param instrumenter [#instrument, nil] e.g. ActiveSupport::Notifications;
+    #   see Clicksend::Instrumentation for the events and their payloads
     # @param adapter [Symbol, Array, nil] Faraday adapter (default Net::HTTP)
     # @param transport [#call, nil] replaces the HTTP layer entirely (see
-    #   Clicksend::Transport); +timeout+, +open_timeout+ and +adapter+ are then
-    #   the transport's responsibility
+    #   Clicksend::Transport and Clicksend::Testing::FakeAPI); +timeout+,
+    #   +open_timeout+ and +adapter+ are then the transport's responsibility
     def initialize(
       username: ENV.fetch("CLICKSEND_USERNAME", nil),
       api_key: ENV.fetch("CLICKSEND_API_KEY", nil),
       base_url: DEFAULT_BASE_URL,
       timeout: DEFAULT_TIMEOUT,
       open_timeout: DEFAULT_OPEN_TIMEOUT,
-      max_retries: DEFAULT_MAX_RETRIES,
+      max_retries: nil,
+      retry_policy: nil,
       logger: nil,
+      instrumenter: nil,
       adapter: nil,
       transport: nil
     )
@@ -56,32 +70,39 @@ module Clicksend
       @base_url = normalize_base_url!(base_url)
       @timeout = positive_number!(timeout, "timeout")
       @open_timeout = positive_number!(open_timeout, "open_timeout")
-      unless max_retries.is_a?(Integer) && max_retries >= 0
-        raise ConfigurationError, "max_retries must be a non-negative Integer"
+      @retry_policy = build_retry_policy(max_retries, retry_policy)
+      @instrumenter = instrumenter || Instrumentation::Null
+      unless @instrumenter.respond_to?(:instrument)
+        raise ConfigurationError, "instrumenter must respond to #instrument(name, payload) { ... }"
       end
-      @max_retries = max_retries
 
       @settings = {
         username: @username, api_key: api_key, base_url: @base_url, timeout: @timeout,
-        open_timeout: @open_timeout, max_retries: @max_retries, logger: logger,
-        adapter: adapter, transport: transport
+        open_timeout: @open_timeout, max_retries: max_retries, retry_policy: retry_policy, logger: logger,
+        instrumenter: instrumenter, adapter: adapter, transport: transport
       }.freeze
 
       @connection = Connection.new(
         transport: transport || Transport::Faraday.new(base_url: @base_url, timeout: @timeout, open_timeout: @open_timeout, adapter: adapter),
-        retry_policy: RetryPolicy.new(max_retries: @max_retries),
+        retry_policy: @retry_policy,
         headers: {
           "Authorization" => "Basic #{["#{@username}:#{api_key}"].pack("m0")}",
           "Accept" => "application/json",
           "User-Agent" => "clicksend-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
         },
-        logger: logger
+        logger: logger,
+        instrumenter: @instrumenter
       )
       @account = Resources::Account.new(self)
       @sms = Resources::SMS.new(self)
       freeze
     end
 
+    # Retries allowed after a failed attempt (from the retry policy).
+    def max_retries
+      retry_policy.max_retries
+    end
+
     # Calls any ClickSend v3 endpoint, wrapped by this gem or not.
     #
     #   client.request(:get, "/v3/sms/history", query: {date_from: (Time.now - 86_400).to_i})
@@ -98,21 +119,27 @@ module Clicksend
     #   it may already have reached ClickSend (timeouts, 5xx). Defaults to true
     #   for GET only: ClickSend uses POST/PUT for operations such as sending
     #   messages and buying credit, so they are not assumed to be repeatable.
+    #   A failure of a non-idempotent request that may have been processed is
+    #   a Clicksend::AmbiguousRequestError.
+    # @param operation [String, nil] a label for logs and instrumentation,
+    #   e.g. "templates.create"; wrapped methods use names like "sms.deliver"
     # @return [Clicksend::Response]
     # @raise [Clicksend::Error] see the error hierarchy in errors.rb
-    def request(method, path, query: nil, body: nil, idempotent: nil)
+    def request(method, path, query: nil, body: nil, idempotent: nil, operation: nil)
       method = method.to_s.downcase.to_sym
       unless Connection::HTTP_METHODS.include?(method)
         raise ArgumentError, "unsupported HTTP method #{method.inspect}; use one of #{Connection::HTTP_METHODS.join(", ")}"
       end
       validate_path!(path)
       raise ArgumentError, "query must be a Hash" unless query.nil? || query.is_a?(Hash)
+      raise ArgumentError, "operation must be a String" unless operation.nil? || operation.is_a?(String)
 
       @connection.request(
         method, path,
         query: query&.compact,
         body: body,
-        idempotent: idempotent.nil? ? method == :get : idempotent
+        idempotent: idempotent.nil? ? method == :get : idempotent == true,
+        operation: operation
       )
     end
 
@@ -122,17 +149,21 @@ module Clicksend
     #   page.auto_paging_each { |message| ... }
     #
     # @return [Clicksend::Page]
-    def paginate(path, query: {}, page: nil, limit: nil)
-      Page.fetch(self, path, query: query, page: page, limit: limit)
+    def paginate(path, query: {}, page: nil, limit: nil, operation: nil)
+      Page.fetch(self, path, query: query, page: page, limit: limit, operation: operation)
     end
 
     # Returns a new client with some settings changed, e.g. a subaccount's
     # credentials or a shorter timeout for a latency-sensitive code path.
+    # Overriding +max_retries+ replaces the retry policy, and vice versa.
     def with(**overrides)
       unknown = overrides.keys - @settings.keys
       raise ArgumentError, "unknown setting(s): #{unknown.join(", ")}" unless unknown.empty?
 
-      self.class.new(**@settings, **overrides)
+      settings = @settings
+      settings = settings.merge(retry_policy: nil) if overrides.key?(:max_retries)
+      settings = settings.merge(max_retries: nil) if overrides.key?(:retry_policy)
+      self.class.new(**settings, **overrides)
     end
 
     def inspect
@@ -150,6 +181,16 @@ module Clicksend
       raise ConfigurationError, "Missing ClickSend #{name}: pass #{name}: or set #{env_name}"
     end
 
+    def build_retry_policy(max_retries, retry_policy)
+      unless max_retries.nil? || retry_policy.nil?
+        raise ConfigurationError, "pass max_retries: or retry_policy:, not both"
+      end
+      return RetryPolicy.new(max_retries: max_retries.nil? ? DEFAULT_MAX_RETRIES : max_retries) if retry_policy.nil?
+      return retry_policy if retry_policy.respond_to?(:delay) && retry_policy.respond_to?(:max_retries)
+
+      raise ConfigurationError, "retry_policy must respond to #delay(error:, attempt:) and #max_retries"
+    end
+
     def positive_number!(value, name)
       return value if value.is_a?(Numeric) && value.positive?
 

data/lib/clicksend/connection.rb

@@ -4,8 +4,12 @@ require "json"
 
 module Clicksend
   # Runs one logical API call over a transport: encodes the JSON body, parses
-  # the response envelope, maps failures to Clicksend errors, retries when the
-  # retry policy says it is safe, and logs a one-line summary per attempt.
+  # the response envelope, maps failures to Clicksend errors, retries when it
+  # is safe, and reports each call to the logger and instrumenter.
+  #
+  # Whether a failure may be retried at all is decided here, from what is
+  # known about the failure, and cannot be changed by configuration. The retry
+  # policy only chooses the delay and enforces the retry budget.
   #
   # @api private Use Client#request instead.
   class Connection
@@ -19,70 +23,211 @@ module Clicksend
       429 => RateLimitError
     }.freeze
 
+    # How much is known about a failed attempt, which decides retries and
+    # ambiguity:
+    #
+    # [:rate_limited] HTTP 429: not processed (ClickSend's documentation)
+    # [:not_sent]     failed before the request was written
+    # [:unknown]      may have been processed: read timeout, reset, TLS, 5xx
+    # [:undocumented] an error inside a 2xx body, or an unreadable 2xx body
+    # [:rejected]     any other 4xx: ClickSend refused the request
+    RETRY_ALWAYS = %i[rate_limited not_sent].freeze
+    MAY_HAVE_BEEN_PROCESSED = %i[unknown undocumented].freeze
+
     # @param headers [Hash] sent with every request (authentication, User-Agent)
-    def initialize(transport:, retry_policy:, headers: {}, logger: nil)
+    # @param instrumenter [#instrument] see Clicksend::Instrumentation
+    def initialize(transport:, retry_policy:, headers: {}, logger: nil, instrumenter: Instrumentation::Null)
       @transport = transport
       @retry_policy = retry_policy
       @headers = headers.dup.freeze
       @logger = logger
+      @instrumenter = instrumenter
     end
 
     # @return [Clicksend::Response]
     # @raise [Clicksend::Error]
-    def request(method, path, query: nil, body: nil, idempotent: false)
+    def request(method, path, query: nil, body: nil, idempotent: false, operation: nil)
       headers = @headers
       unless body.nil?
         headers = headers.merge("Content-Type" => "application/json")
         body = JSON.generate(body)
       end
 
+      call = {method: method, path: path, operation: operation, idempotent: idempotent}
+      instrumented(call) { |payload| run(call, query, body, headers, payload) }
+    end
+
+    # Never show the Authorization header.
+    def inspect
+      "#<#{self.class.name}>"
+    end
+
+    private
+
+    # Runs the call inside the instrumenter's request.clicksend block, but
+    # never lets the instrumenter change the outcome: once the block has run,
+    # whatever the instrumenter raises (a failing subscriber, a frozen
+    # payload, ...) is logged and the call's own result or error wins. Without
+    # this, a metrics outage after an accepted send would surface as a
+    # non-Clicksend error that a job runner retries: a duplicate SMS.
+    #
+    # +state+ moves :pending -> :running -> :done. Only an exception that
+    # arrives once the request is :done can be the instrumenter's own, and
+    # only then is it ignored. Anything raised while the request is :running
+    # propagates: #run turns every failure it can foresee into a
+    # Clicksend::Error, so that is a genuine bug, never something to hide
+    # (hiding it once made #request return nil after an accepted send). A
+    # second call of the block raises instead of sending again.
+    def instrumented(call)
+      payload = {http_method: call[:method], path: reported_path(call[:path]), operation: call[:operation], idempotent: call[:idempotent]}
+      state = :pending
+      outcome = nil
+      begin
+        @instrumenter.instrument("request.clicksend", payload) do
+          raise ConfigurationError, "the instrumenter ran the request block twice; #instrument must yield once" unless state == :pending
+
+          state = :running
+          outcome = begin
+            yield payload
+          rescue Error => e
+            e
+          end
+          state = :done
+          # Raise inside the block so ActiveSupport records the exception.
+          outcome.is_a?(Error) ? raise(outcome) : outcome
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise unless state == :done && e.is_a?(StandardError) && !e.equal?(outcome)
+
+        log(:warn) { "instrumenter raised #{e.class.name} for #{call[:method].upcase} #{reported_path(call[:path])}; ignored" }
+      end
+      raise ConfigurationError, "the instrumenter did not run the request: #instrument must yield" if state == :pending
+      raise outcome if outcome.is_a?(Error)
+
+      outcome
+    end
+
+    def run(call, query, body, headers, payload)
       attempt = 0
       loop do
-        outcome, retry_allowed = attempt_request(method, path, query, body, headers)
-        return outcome if outcome.is_a?(Response)
+        info = RequestInfo.new(http_method: call[:method], path: reported_path(call[:path]), operation: call[:operation],
+          idempotent: call[:idempotent], attempts: attempt + 1)
+        outcome, kind = attempt_request(call, query, body, headers)
+        if outcome.is_a?(Response)
+          record(payload, attempts: info.attempts, http_status: outcome.http_status, response_code: outcome.response_code, ambiguous: false)
+          return outcome.with(request: info)
+        end
 
         error = outcome
-        delay = retry_allowed && @retry_policy.delay(error: error, attempt: attempt, idempotent: idempotent)
-        raise error unless delay
+        error.request = info
+        delay = retry_delay(error, kind, attempt, call[:idempotent])
+        unless delay
+          error.mark_ambiguous! if !call[:idempotent] && MAY_HAVE_BEEN_PROCESSED.include?(kind)
+          record(payload, attempts: info.attempts, http_status: error_status(error), response_code: error_code(error), ambiguous: error.ambiguous?)
+          raise error
+        end
 
         attempt += 1
-        log(:warn) do
-          "#{method.upcase} #{path} failed (#{error.class.name}), retrying in #{format("%.2f", delay)}s " \
-            "(retry #{attempt} of #{@retry_policy.max_retries})"
-        end
+        announce_retry(call, error, attempt, delay)
         Kernel.sleep(delay)
       end
     end
 
-    # Never show the Authorization header.
-    def inspect
-      "#<#{self.class.name}>"
+    # One HTTP attempt. Returns a Response, or [error, kind]. Errors are
+    # returned rather than raised so the retry decision can use facts about
+    # this attempt without storing state on the (shared) Connection.
+    #
+    # Errors raised by the transport are copied before the connection adds
+    # context, so a frozen or reused exception instance is never modified.
+    # Anything a custom transport raises that is not a Clicksend::Error is
+    # treated as a connection failure that may have been sent.
+    def attempt_request(call, query, body, headers)
+      started = monotonic_now
+      raw = begin
+        @transport.call(call[:method], call[:path], query: query, body: body, headers: headers)
+      rescue ConnectionError => e
+        return [e.dup, e.request_may_have_been_sent? ? :unknown : :not_sent]
+      rescue MalformedResponseError => e
+        return [e.dup, :undocumented]
+      rescue Error => e
+        return [e.dup, :unknown] # any other Clicksend error from a custom transport: outcome unknown
+      rescue => e
+        return [wrap_failure(ConnectionError, "The transport failed", e), :unknown]
+      end
+      log(:info) { "#{call[:method].upcase} #{reported_path(call[:path])} -> #{raw.status} (#{elapsed_ms(started)}ms)" }
+      begin
+        interpret(raw)
+      rescue MalformedResponseError => e
+        [e, :undocumented]
+      rescue => e
+        # A response this gem cannot even read (e.g. a body that is not valid
+        # in its declared charset) is undocumented: ambiguous for a send.
+        [wrap_failure(MalformedResponseError, "Could not read ClickSend's response", e), :undocumented]
+      end
     end
 
-    private
-
-    # One HTTP attempt. Returns a Response, or [error, retry_allowed]. Errors
-    # are returned rather than raised so the retry decision can use facts
-    # about this attempt without storing state on the (shared) Connection.
-    def attempt_request(method, path, query, body, headers)
-      started = monotonic_now
-      raw = @transport.call(method, path, query: query, body: body, headers: headers)
-      log(:info) { "#{method.upcase} #{path} -> #{raw.status} (#{elapsed_ms(started)}ms)" }
-      interpret(raw)
-    rescue ConnectionError => e
-      [e, true]
+    # Raised (and rescued) inside the caller's rescue, so #cause is the
+    # original exception. Only its class is copied into the message: a
+    # foreign exception's message may hold a URL, a query string or a body.
+    def wrap_failure(error_class, text, error)
+      raise error_class, "#{text}: #{error.class.name}"
+    rescue error_class => e
+      e
     end
 
-    # @return [Response, Array(APIError, Boolean)]
+    # @return [Response, Array(Error, Symbol)]
     def interpret(raw)
+      unless raw.respond_to?(:status) && raw.status.is_a?(Integer) && raw.status.between?(100, 599)
+        raise MalformedResponseError, "The transport returned no valid HTTP status"
+      end
+
       body = parse_body(raw)
       status = effective_status(raw.status, body)
       return Response.new(http_status: raw.status, headers: raw.headers, body: body) if success?(status)
 
+      error = api_error(status, raw, body)
       # An error reported only inside a 2xx body is undocumented for v3, so
-      # nothing is known about whether ClickSend acted on the request: never
-      # retry it, whatever the reported code.
-      [api_error(status, raw, body), status == raw.status]
+      # nothing is known about whether ClickSend acted on the request.
+      kind = if status != raw.status then :undocumented
+      elsif status == 429 then :rate_limited
+      elsif status >= 500 then :unknown
+      elsif status >= 400 then :rejected
+      else :undocumented # 1xx/3xx: not expected from ClickSend (redirects are not followed)
+      end
+      [error, kind]
+    end
+
+    # The safety rule, then the policy's timing and budget.
+    #
+    # The connection also enforces the policy's own max_retries, so a policy
+    # whose #delay never says no still cannot loop forever.
+    def retry_delay(error, kind, attempt, idempotent)
+      eligible = RETRY_ALWAYS.include?(kind) || (kind == :unknown && idempotent)
+      return unless eligible
+
+      budget = @retry_policy.max_retries
+      return unless budget.is_a?(Integer) && attempt < budget
+
+      delay = @retry_policy.delay(error: error, attempt: attempt)
+      delay = Float(delay) if delay.is_a?(Numeric)
+      delay if delay.is_a?(Float) && delay.finite? && delay >= 0
+    rescue => e
+      # A broken policy stops retrying (the safe direction) and keeps the
+      # request's own error.
+      log(:warn) { "retry policy raised #{e.class.name}; not retrying" }
+      nil
+    end
+
+    def announce_retry(call, error, attempt, delay)
+      log(:warn) do
+        "#{call[:method].upcase} #{reported_path(call[:path])} failed (#{error.class.name}), retrying in #{format("%.2f", delay)}s " \
+          "(retry #{attempt} of #{@retry_policy.max_retries})"
+      end
+      payload = {http_method: call[:method], path: reported_path(call[:path]), operation: call[:operation], attempt: attempt,
+                 delay: delay, error_class: error.class.name, http_status: error_status(error)}
+      @instrumenter.instrument("retry.clicksend", payload) {}
+    rescue => e
+      log(:warn) { "instrumenter raised #{e.class.name} for retry.clicksend; ignored" }
     end
 
     def api_error(status, raw, body)
@@ -105,7 +250,7 @@ module Clicksend
     # Returns the parsed JSON, nil for an empty body, or the raw String when an
     # error response isn't JSON (e.g. an HTML page from a proxy).
     def parse_body(raw)
-      return nil if raw.body.strip.empty?
+      return nil if raw.body.b.strip.empty?
 
       JSON.parse(raw.body, freeze: true)
     rescue JSON::ParserError
@@ -134,12 +279,38 @@ module Clicksend
       (200..299).cover?(status)
     end
 
+    def error_status(error)
+      error.http_status if error.respond_to?(:http_status)
+    end
+
+    def error_code(error)
+      error.response_code if error.respond_to?(:response_code)
+    end
+
     def string_or_nil(value)
       value.is_a?(String) ? value : nil
     end
 
+    # Adds the outcome to the request.clicksend payload. The payload belongs
+    # to the instrumenter's subscribers too; if one froze or replaced it,
+    # the outcome is simply not recorded.
+    def record(payload, **outcome)
+      payload.update(outcome)
+    rescue
+      nil
+    end
+
+    # A failing logger must not turn a completed request into an error.
     def log(level)
       @logger&.public_send(level, "[clicksend] #{yield}")
+    rescue
+      nil
+    end
+
+    # The path as reported in errors, logs and instrumentation: never with a
+    # query string or fragment, even if one was written into the path.
+    def reported_path(path)
+      path.split(/[?#]/, 2).first
     end
 
     def monotonic_now