recurly 4.80.0 → 4.82.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0e6c839c677863f0df569868d3aea1a97574cc249b3f0dfdfb6f71f4029b592
-  data.tar.gz: f766e6760fb8c96a976b89d3c4a6e62536a0eae21fa3b36996da0400f9a700f9
+  metadata.gz: f18ba4644a7a18b9af8bf1d8e2105b618e4b72c60ffece627e9ce0ac5c975df3
+  data.tar.gz: af4b805af51738af015cc8b3b75366b626e06c8cb4216b63e13c61b1c4da5d80
 SHA512:
-  metadata.gz: 8edd7d42e45fd761b8620c37a32dec83c8a90b3cf14cabd2b6dc6b5f45dc436f002da5967cf4ea4ce6299275aec863a5e0c0ae691b82bd933cecae9cc53cb1ee
-  data.tar.gz: 9acd5bcd20f19574e54bb8484954cf0d1d420d67197209b823d918aa6ba1b2a7962b1dd2ded9e45ef88ba37574bc9315dc4bec1afe8ad13b69ff5726d1ac2111
+  metadata.gz: 4b775860b96876758f1f5d80bde246d290816a2ac5363543c33092de01dfc11feb9c8392bac719fd62a7e86950565f0f33bc4af931683f8dfad859607984e504
+  data.tar.gz: 283ad6f4743597ffd73bfec1bef644896c9d557fe255b0cf270ed1838a393ae5de245be001f8dc0d5b7d489675dab409966c7eff9383e2a3b16eedb9c2bad9d5

data/.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 4.80.0
+current_version = 4.82.0
 parse = (?P<major>\d+)
 	\.(?P<minor>\d+)
 	\.(?P<patch>\d+)

data/.github/workflows/ci.yml

@@ -1,7 +1,9 @@
 name: CI
-on: [push]
-concurrency: 
-  group: ${{ github.ref }}
+on:
+  push:
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 jobs:
   build:

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [4.82.0](https://github.com/recurly/recurly-client-ruby/tree/4.82.0) (2026-09-15)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.81.0...4.82.0)
+
+
+
+
+
+## [4.81.0](https://github.com/recurly/recurly-client-ruby/tree/4.81.0) (2026-09-09)
+
+[Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.80.0...4.81.0)
+
+
+**Merged Pull Requests**
+
+- Generated Latest Changes for v2021-02-25 [#968](https://github.com/recurly/recurly-client-ruby/pull/968) ([recurly-integrations](https://github.com/recurly-integrations))
+- Relax base64 dependency to allow 0.3.x [#965](https://github.com/recurly/recurly-client-ruby/pull/965) ([romanoff](https://github.com/romanoff))
+
+
+
 ## [4.80.0](https://github.com/recurly/recurly-client-ruby/tree/4.80.0) (2026-07-02)
 
 [Full Changelog](https://github.com/recurly/recurly-client-ruby/compare/4.79.0...4.80.0)

data/GETTING_STARTED.md

@@ -5,7 +5,7 @@ This repository houses the official ruby client for Recurly's V3 API.
 In your Gemfile, add `recurly` as a dependency.
 
 ```ruby
-gem 'recurly', '~> 4.80'
+gem 'recurly', '~> 4.82'
 ```
 
 > *Note*: We try to follow [semantic versioning](https://semver.org/) and will only apply breaking changes to major versions.

data/README.md

@@ -12,6 +12,33 @@ This repository houses the official ruby client for Recurly's V3 API.
 
 Getting Started Guide and reference documentation can be found on [Github Pages](https://recurly.github.io/recurly-client-ruby/).
 
+## Custom HTTP Adapter
+
+The client ships with a default `Net::HTTP`-backed transport, but you can inject
+your own HTTP layer (for observability, proxy/TLS control, or transport mocking)
+by passing an adapter that responds to `#call`:
+
+```ruby
+client = Recurly::Client.new(api_key: API_KEY, http_adapter: MyAdapter.new)
+```
+
+An adapter must implement:
+
+```ruby
+# @return [Recurly::HTTP::AdapterResponse]
+# @raise  [Recurly::Errors::TransportError] on transport-level failure only
+def call(method, url, headers, body, open_timeout: nil, read_timeout: nil)
+end
+```
+
+- `method` is a `Recurly::HTTP::HttpMethod` string (`"GET"`, `"POST"`, ...).
+- `url` is an **absolute** URL (scheme + host + path + query).
+- `headers` is a plain `Hash` of app-level headers (the SDK owns `Authorization`,
+  `Idempotency-Key`, `Content-Type`, etc.).
+- `body` is a serialized `String` or `nil`.
+- HTTP `4xx`/`5xx` responses must be **returned** as an `AdapterResponse`, never
+  raised. Only genuine transport failures raise `Recurly::Errors::TransportError`.
+
 ## Contributing
 
 Please see our [Contributing Guide](CONTRIBUTING.md).

data/lib/recurly/client.rb

@@ -24,6 +24,22 @@ module Recurly
     MAX_RETRIES = 3
     LOG_LEVELS = %i(debug info warn error fatal).freeze
     BASE36_ALPHABET = (("0".."9").to_a + ("a".."z").to_a).freeze
+
+    # Vendored HTTP status → reason-phrase table. Used to synthesize a
+    # reason_phrase when a (custom) adapter did not surface one. On the default
+    # path the adapter provides Net::HTTP's reason phrase, so this is not
+    # consulted and behavior is byte-identical. Phrases are bare (no status code
+    # prefix) since callers build "#{code}: #{phrase}".
+    HTTP_STATUS_MESSAGES = {
+      200 => "OK", 201 => "Created", 202 => "Accepted", 204 => "No Content",
+      301 => "Moved Permanently", 302 => "Found", 304 => "Not Modified",
+      400 => "Bad Request", 401 => "Unauthorized", 402 => "Payment Required",
+      403 => "Forbidden", 404 => "Not Found", 406 => "Not Acceptable",
+      409 => "Conflict", 412 => "Precondition Failed", 422 => "Unprocessable Entity",
+      429 => "Too Many Requests", 500 => "Internal Server Error", 502 => "Bad Gateway",
+      503 => "Service Unavailable", 504 => "Gateway Timeout",
+    }.freeze
+
     ALLOWED_OPTIONS = [
       :site_id,
       :open_timeout,
@@ -61,7 +77,7 @@ module Recurly
     # @param ca_file [String] The CA bundle to use when connecting to the API. Defaults to "data/ca-certificates.crt"
     # @param api_key [String] The private API key
     # @param logger [Logger] A logger to use. Defaults to creating a new STDOUT logger with level WARN.
-    def initialize(region: REGION, base_url: API_HOSTS[:us], ca_file: CA_FILE, api_key:, logger: nil, keep_alive_timeout: 600)
+    def initialize(region: REGION, base_url: API_HOSTS[:us], ca_file: CA_FILE, api_key:, logger: nil, keep_alive_timeout: 600, http_adapter: nil)
       raise ArgumentError, "'api_key' must be set to a non-nil value" if api_key.nil?
 
       raise ArgumentError, "Invalid region type. Expected one of: #{API_HOSTS.keys.join(", ")}" if !API_HOSTS.key?(region)
@@ -92,6 +108,12 @@ module Recurly
         log_warn("SECURITY_WARNING", message: msg)
       end
 
+      @http_adapter = http_adapter || HTTP::DefaultHttpAdapter.new(
+        connection_pool: self.class.connection_pool,
+        keep_alive_timeout: @keep_alive_timeout,
+        ca_file: @ca_file,
+      )
+
       # execute block with this client if given
       yield(self) if block_given?
     end
@@ -111,55 +133,57 @@ module Recurly
 
     def head(path, **options)
       validate_options!(**options)
-      request = Net::HTTP::Head.new build_url(path, options)
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::HEAD, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::HEAD, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def get(path, **options)
       validate_options!(**options)
-
-      request = Net::HTTP::Get.new build_url(path, options)
-
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::GET, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::GET, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def post(path, request_data = nil, request_class = nil, **options)
       validate_options!(**options)
-      request = Net::HTTP::Post.new build_url(path, options)
-      request.set_content_type(JSON_CONTENT_TYPE)
-      set_headers(request, options[:headers])
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::POST, options[:headers])
+      body = nil
       if request_data
         request_class.new(request_data).validate!
-        request.body = JSON.dump(request_data)
+        body = JSON.dump(request_data)
       end
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      request = HTTP::Request.new(HTTP::HttpMethod::POST, relative_path, body)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def put(path, request_data = nil, request_class = nil, **options)
       validate_options!(**options)
-      request = Net::HTTP::Put.new build_url(path, options)
-      request.set_content_type(JSON_CONTENT_TYPE)
-      set_headers(request, options[:headers])
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::PUT, options[:headers])
+      body = nil
       if request_data
         request_class.new(request_data).validate!
-        json_body = JSON.dump(request_data)
-        request.body = json_body
+        body = JSON.dump(request_data)
       end
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      request = HTTP::Request.new(HTTP::HttpMethod::PUT, relative_path, body)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     def delete(path, **options)
       validate_options!(**options)
-      request = Net::HTTP::Delete.new build_url(path, options)
-      set_headers(request, options[:headers])
-      http_response = run_request(request, options)
-      handle_response! request, http_response
+      relative_path = build_url(path, options)
+      headers = build_headers(HTTP::HttpMethod::DELETE, options[:headers])
+      request = HTTP::Request.new(HTTP::HttpMethod::DELETE, relative_path, nil)
+      response = run_request(request, headers, options)
+      handle_response! request, response
     end
 
     private
@@ -171,80 +195,110 @@ module Recurly
       attr_accessor :connection_pool
     end
 
-    def run_request(request, options = {})
-      self.class.connection_pool.with_connection(uri: @base_uri, keep_alive_timeout: @keep_alive_timeout, ca_file: @ca_file) do |http|
-        set_http_options(http, options)
+    def run_request(request, headers, options = {})
+      method = request.method
+      body = request.body
+      url = request_url(request.path)
+      open_timeout = options[:open_timeout]
+      read_timeout = options[:read_timeout]
 
-        retries = 0
+      retries = 0
 
-        begin
-          http.start unless http.started?
-
-          log_attrs = {
-            method: request.method,
-            path: request.path,
-          }
-          if @logger.level < Logger::INFO
-            log_attrs[:request_body] = request.body
-            # No need to log the authorization header
-            headers = request.to_hash.reject { |k, _| k&.downcase == "authorization" }
-            log_attrs[:request_headers] = headers
-          end
+      log_attrs = {
+        method: method,
+        path: request.path,
+      }
+      if @logger.level < Logger::INFO
+        log_attrs[:request_body] = body
+        # No need to log the authorization header
+        loggable_headers = headers.reject { |k, _| k&.downcase == "authorization" }
+        log_attrs[:request_headers] = loggable_headers
+      end
 
-          log_info("Request", **log_attrs)
-          start = Time.now
-          response = http.request(request)
-          elapsed = Time.now - start
+      begin
+        log_info("Request", **log_attrs)
+        start = Time.now
+        response = @http_adapter.call(method, url, headers, body, open_timeout: open_timeout, read_timeout: read_timeout)
+        elapsed = Time.now - start
 
-          # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response
-          if response.kind_of?(Net::HTTPServerError) && request.is_a?(Net::HTTP::Get)
-            retries += 1
+        # GETs are safe to retry after a server error, requests with an Idempotency-Key will return the prior response.
+        # This is a SINGLE inline re-issue (not a loop) that shares the same `retries` counter as the transport rescue.
+        if response.status_code >= 500 && method == HTTP::HttpMethod::GET
+          retries += 1
+          if retries < MAX_RETRIES
             log_info("Retrying", retries: retries, **log_attrs)
             start = Time.now
-            response = http.request(request) if retries < MAX_RETRIES
+            response = @http_adapter.call(method, url, headers, body, open_timeout: open_timeout, read_timeout: read_timeout)
             elapsed = Time.now - start
           end
+        end
 
-          if @logger.level < Logger::INFO
-            log_attrs[:response_body] = response.body
-            log_attrs[:response_headers] = response.to_hash
-          end
-          log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.code, **log_attrs)
-
-          response
-        rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ECONNABORTED,
-               Errno::EPIPE, Errno::ETIMEDOUT, Net::OpenTimeout, EOFError, SocketError => ex
-          retries += 1
-          if retries < MAX_RETRIES
-            retry
-          end
+        if @logger.level < Logger::INFO
+          log_attrs[:response_body] = response.body
+          log_attrs[:response_headers] = response.headers
+        end
+        log_info("Response", time_ms: (elapsed * 1_000).floor, status: response.status_code, **log_attrs)
 
-          if ex.kind_of?(Net::OpenTimeout) || ex.kind_of?(Errno::ETIMEDOUT)
-            raise Recurly::Errors::TimeoutError, "Request timed out"
-          end
+        response
+      rescue Recurly::Errors::TransportError => ex
+        retries += 1
+        if retries < MAX_RETRIES
+          retry
+        end
 
-          raise Recurly::Errors::ConnectionFailedError, "Failed to connect to Recurly: #{ex.message}"
-        rescue Timeout::Error
+        case ex.kind
+        when :timeout
           raise Recurly::Errors::TimeoutError, "Request timed out"
-        rescue OpenSSL::SSL::SSLError => ex
+        when :ssl
           raise Recurly::Errors::SSLError, ex.message
-        rescue StandardError => ex
+        when :connection
+          raise Recurly::Errors::ConnectionFailedError, ex.message
+        else
           raise Recurly::Errors::NetworkError, ex.message
         end
       end
     end
 
-    def set_headers(request, additional_headers = {})
+    # Builds the app-level request headers as a plain Hash. Header names are
+    # compared case-insensitively so a caller-supplied header (any case)
+    # overrides the SDK default instead of producing a duplicate.
+    def build_headers(method, additional_headers = {})
+      headers = {}
+
+      # Content-Type must be applied FIRST for bodied verbs, so caller headers
+      # can override it (parity with the old set_content_type-then-set_headers order).
+      if method == HTTP::HttpMethod::POST || method == HTTP::HttpMethod::PUT
+        headers["Content-Type"] = JSON_CONTENT_TYPE
+      end
+
       # TODO this is undocumented until we finalize it
-      additional_headers.each { |header, v| request[header] = v } if additional_headers
+      if additional_headers
+        additional_headers.each { |header, v| set_header(headers, header, v) }
+      end
 
-      request["Accept"] = "application/vnd.recurly.#{api_version}".chomp # got this method from operations.rb
-      request["Authorization"] = "Basic #{Base64.encode64(@api_key)}".chomp
-      request["User-Agent"] = "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}"
+      set_header(headers, "Accept", "application/vnd.recurly.#{api_version}".chomp) # got this method from operations.rb
+      set_header(headers, "Authorization", "Basic #{Base64.encode64(@api_key)}".chomp)
+      set_header(headers, "User-Agent", "Recurly/#{VERSION}; #{RUBY_DESCRIPTION}")
 
-      unless request.is_a?(Net::HTTP::Get) || request.is_a?(Net::HTTP::Head)
-        request["Idempotency-Key"] ||= generate_idempotency_key
+      unless method == HTTP::HttpMethod::GET || method == HTTP::HttpMethod::HEAD
+        # Only generate an Idempotency-Key if the caller did not supply one (any case).
+        set_header(headers, "Idempotency-Key", generate_idempotency_key) unless header_key?(headers, "Idempotency-Key")
       end
+
+      headers
+    end
+
+    # Sets a header, replacing any existing entry whose name matches
+    # case-insensitively (so we never emit two headers differing only in case).
+    def set_header(headers, name, value)
+      existing = headers.keys.find { |k| k.to_s.downcase == name.to_s.downcase }
+      headers.delete(existing) if existing
+      headers[name] = value
+    end
+
+    # @return [Boolean] whether a header (case-insensitive) is already present
+    def header_key?(headers, name)
+      headers.keys.any? { |k| k.to_s.downcase == name.to_s.downcase }
     end
 
     # from https://github.com/rails/rails/blob/6-0-stable/activesupport/lib/active_support/core_ext/securerandom.rb
@@ -256,21 +310,16 @@ module Recurly
       end.join
     end
 
-    def set_http_options(http, options)
-      http.open_timeout = options[:open_timeout] || 20
-      http.read_timeout = options[:read_timeout] || 60
-    end
-
-    def handle_response!(request, http_response)
-      response = HTTP::Response.new(http_response, request)
-      raise_api_error!(http_response, response) unless http_response.kind_of?(Net::HTTPSuccess)
+    def handle_response!(request, adapter_response)
+      response = HTTP::Response.new(adapter_response, request)
+      raise_api_error!(adapter_response, response) unless adapter_response.status_code.between?(200, 299)
       resource = if response.body
-          if http_response.content_type&.include?(JSON_CONTENT_TYPE)
+          if response.content_type&.include?(JSON_CONTENT_TYPE)
             JSONParser.parse(self, response.body)
-          elsif BINARY_TYPES.include?(http_response.content_type)
+          elsif BINARY_TYPES.include?(response.content_type)
             FileParser.parse(response.body)
           else
-            raise Recurly::Errors::InvalidContentTypeError, "Unexpected content type: #{http_response.content_type}"
+            raise Recurly::Errors::InvalidContentTypeError, "Unexpected content type: #{response.content_type}"
           end
         else
           Resources::Empty.new
@@ -280,28 +329,37 @@ module Recurly
       resource
     end
 
-    def raise_api_error!(http_response, response)
-      if response.content_type.include?(JSON_CONTENT_TYPE)
+    def raise_api_error!(adapter_response, response)
+      if response.content_type&.include?(JSON_CONTENT_TYPE) && response.body
         error = JSONParser.parse(self, response.body)
         begin
           error_class = Errors::APIError.error_class(error.type)
           raise error_class.new(error.message, response, error)
         rescue NameError
-          error_class = Errors::APIError.from_response(http_response)
+          error_class = Errors::APIError.from_response(adapter_response)
           raise error_class.new("Unknown Error", response, error)
         end
       end
 
-      error_class = Errors::APIError.from_response(http_response)
+      error_class = Errors::APIError.from_response(adapter_response)
+      status_line = status_line_for(adapter_response)
 
       if error_class <= Recurly::Errors::APIError
-        error = Recurly::Resources::Error.new(message: "#{http_response.code}: #{http_response.message}")
+        error = Recurly::Resources::Error.new(message: status_line)
         raise error_class.new(error.message, response, error)
       else
-        raise error_class, "#{http_response.code}: #{http_response.message}"
+        raise error_class, status_line
       end
     end
 
+    # Builds a "<code>: <phrase>" status line, falling back to the vendored
+    # reason-phrase table and omitting the trailing ": " entirely when no
+    # phrase can be found (e.g. a custom adapter on an uncommon status code).
+    def status_line_for(adapter_response)
+      phrase = adapter_response.reason_phrase || HTTP_STATUS_MESSAGES[adapter_response.status_code]
+      phrase ? "#{adapter_response.status_code}: #{phrase}" : adapter_response.status_code.to_s
+    end
+
     def read_headers(response)
       if !@_ignore_deprecation_warning && response.headers["Recurly-Deprecated"]&.upcase == "TRUE"
         log_warn("DEPRECTATION WARNING", message: "Your current API version \"#{api_version}\" is deprecated and will be sunset on #{response.headers["Recurly-Sunset-Date"]}")
@@ -359,6 +417,15 @@ module Recurly
       @keep_alive_timeout = keep_alive_timeout
     end
 
+    # Absolute URL for the adapter: base_url ORIGIN (scheme, host, port) + the
+    # relative path. Any path/trailing-slash on base_url is ignored, matching the
+    # pre-adapter behavior of opening by host:port and sending the path alone.
+    def request_url(relative_path)
+      origin = "#{@base_uri.scheme}://#{@base_uri.host}"
+      origin += ":#{@base_uri.port}" unless @base_uri.port == @base_uri.default_port
+      origin + relative_path
+    end
+
     def build_url(path, options)
       path = scope_by_site(path, options)
       query_params = map_array_params(options.fetch(:params, {}))

data/lib/recurly/errors/api_errors.rb

@@ -4,87 +4,57 @@
 # need and we will usher them to the appropriate places.
 module Recurly
   module Errors
-    ERROR_MAP = {
-      "500" => "InternalServerError",
-      "502" => "BadGatewayError",
-      "503" => "ServiceUnavailableError",
-      "504" => "TimeoutError",
-      "304" => "NotModifiedError",
-      "400" => "BadRequestError",
-      "401" => "UnauthorizedError",
-      "402" => "PaymentRequiredError",
-      "403" => "ForbiddenError",
-      "404" => "NotFoundError",
-      "406" => "NotAcceptableError",
-      "412" => "PreconditionFailedError",
-      "422" => "UnprocessableEntityError",
-      "429" => "TooManyRequestsError",
-    }
+    class APIError
+      self.error_map = {
+        "500" => "InternalServerError",
+        "502" => "BadGatewayError",
+        "503" => "ServiceUnavailableError",
+        "504" => "TimeoutError",
+        "304" => "NotModifiedError",
+        "400" => "BadRequestError",
+        "401" => "UnauthorizedError",
+        "402" => "PaymentRequiredError",
+        "403" => "ForbiddenError",
+        "404" => "NotFoundError",
+        "406" => "NotAcceptableError",
+        "412" => "PreconditionFailedError",
+        "422" => "UnprocessableEntityError",
+        "429" => "TooManyRequestsError",
+      }.freeze
+    end
 
     class ResponseError < Errors::APIError; end
-
     class ServerError < ResponseError; end
-
     class InternalServerError < ServerError; end
-
     class ServiceNotAvailableError < InternalServerError; end
-
     class TaxServiceError < InternalServerError; end
-
     class BadGatewayError < ServerError; end
-
     class ServiceUnavailableError < ServerError; end
-
     class TimeoutError < ServerError; end
-
     class RedirectionError < ResponseError; end
-
     class NotModifiedError < ResponseError; end
-
     class ClientError < Errors::APIError; end
-
     class BadRequestError < ClientError; end
-
     class InvalidContentTypeError < BadRequestError; end
-
     class UnauthorizedError < ClientError; end
-
     class PaymentRequiredError < ClientError; end
-
     class ForbiddenError < ClientError; end
-
     class InvalidApiKeyError < ForbiddenError; end
-
     class InvalidPermissionsError < ForbiddenError; end
-
     class NotFoundError < ClientError; end
-
     class NotAcceptableError < ClientError; end
-
     class UnknownApiVersionError < NotAcceptableError; end
-
     class UnavailableInApiVersionError < NotAcceptableError; end
-
     class InvalidApiVersionError < NotAcceptableError; end
-
     class PreconditionFailedError < ClientError; end
-
     class UnprocessableEntityError < ClientError; end
-
     class ValidationError < UnprocessableEntityError; end
-
     class MissingFeatureError < UnprocessableEntityError; end
-
     class TransactionError < UnprocessableEntityError; end
-
     class SimultaneousRequestError < UnprocessableEntityError; end
-
     class ImmutableSubscriptionError < UnprocessableEntityError; end
-
     class InvalidTokenError < UnprocessableEntityError; end
-
     class TooManyRequestsError < ClientError; end
-
     class RateLimitedError < TooManyRequestsError; end
   end
 end

data/lib/recurly/errors/network_errors.rb

@@ -3,5 +3,30 @@ module Recurly
     class NetworkError < APIError; end
     class ConnectionFailedError < NetworkError; end
     class SSLError < NetworkError; end
+
+    # Neutral transport error raised by HTTP adapters for ALL transport-level
+    # failures (timeouts, connection failures, SSL errors, generic network
+    # errors). This is the single error class the client's retry loop rescues.
+    #
+    # The +kind+ symbol (+:timeout+, +:connection+, +:ssl+, +:network+) lets the
+    # client reproduce its historical typed-error mapping after retries are
+    # exhausted, without needing to know about adapter-specific exception classes.
+    # Custom adapters that only set +:network+ degrade gracefully to +NetworkError+.
+    class TransportError < NetworkError
+      # @return [Symbol] one of +:timeout+, +:connection+, +:ssl+, +:network+
+      attr_reader :kind
+
+      # @return [Exception, nil] the underlying transport exception, if any.
+      #   Named distinctly from Ruby's built-in +Exception#cause+ (which is
+      #   auto-populated on +raise+ inside a +rescue+ and read by Sentry,
+      #   logging frameworks, and +pp+) so we don't shadow it.
+      attr_reader :original_exception
+
+      def initialize(message, kind: :network, cause: nil)
+        super(message)
+        @kind = kind
+        @original_exception = cause
+      end
+    end
   end
 end

data/lib/recurly/errors.rb

@@ -5,6 +5,19 @@ module Recurly
       #   @return [Recurly::Resources::Error] The {Recurly::Resources::Error} object
       attr_reader :recurly_error
 
+      class << self
+        private
+
+        # @param map [Hash] Maps response status codes (String) to error class names (String).
+        attr_writer :error_map
+
+        # Maps a response status code (String) to an error class name (String).
+        # Set by the generated errors/api_errors.rb file via .error_map=.
+        def error_map
+          @error_map || raise("error_map must be set by the generated api_errors.rb file")
+        end
+      end
+
       # Looks up an Error class by name
       # @example
       #   Errors.error_class('BadRequestError')
@@ -23,8 +36,8 @@ module Recurly
       # @param response [Net::Response]
       # @return [Errors::APIError]
       def self.from_response(response)
-        if Recurly::Errors::ERROR_MAP.has_key?(response.code)
-          Recurly::Errors.const_get(Recurly::Errors::ERROR_MAP[response.code])
+        if error_map.has_key?(response.code)
+          Recurly::Errors.const_get(error_map[response.code])
         else
           Recurly::Errors::APIError
         end