fulfil_api 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2dd30142d140730335b3f184bc28c0fd897af19246a8794ec5d416b1a335b2a
-  data.tar.gz: b81436ad499dfdd14ea84f5651d4670395907ad8090ab4e9eed432c6195da86c
+  metadata.gz: 2971bc621921930210bce77c057d6da8ce549cfe476fb1fc29d72f10c4447303
+  data.tar.gz: 97658bf767d8909e359ad66441de0f81108982c6383070778eb04d3386c2fb3d
 SHA512:
-  metadata.gz: 6dee8c45eea430b8f6e7bfa82b03c3d737dd424cdda363c74680f4acedc9e896c28cfc3bc746e35d33035a863ffed9f995877b267a59e0afae0f2e67f7047d20
-  data.tar.gz: 5873899ac0f65bb6a9e1ecbd74aebd1f45806cee1faed5716c1649e158d83396de15139a93da9347b8b20ba080172c7e2cfa59aca36b6f89a89a4a57207e3167
+  metadata.gz: 020e57b3a676a3c56f2d2b76e5b269010764d3a95f41ef19848f0477e4f77ac9db9871252c68efe77fe35af1fbd6f319d8283f43b578caf7e09e8de4651120a9
+  data.tar.gz: 51af4a10179668acf8977fca9dccfc133bbb25516c7464cb87bd05f9abf0a5926b1631620cf9265a9637b7b0ffa8c7b9a6618bf9ee7b75912005eb3f1722e1a3

data/CHANGELOG.md

@@ -1,5 +1,7 @@
 ## [Unreleased]
 
+- Raise a `FulfilApi::HttpError` instead of a generic `FulfilApi::Error` when a request to Fulfil fails, with a dedicated subclass per HTTP status code (e.g. `FulfilApi::HttpError::TooManyRequests` for a 429). The exception message is now the description reported by Fulfil rather than its serialized response body, and the status code, body and headers are available through `#status_code`, `#response_body` and `#response_headers`. `FulfilApi::HttpError` inherits from `FulfilApi::Error`, so existing rescues keep working.
+
 - Re-enable Ruby's built-in retry for idempotent requests on the persistent connection, which the `net_http_persistent` adapter disables by forcing `max_retries` to `0`. This recovers stale keep-alive sockets transparently instead of surfacing them as read timeouts.
 - Add a `connection_options` configuration option to tune the persistent connection (`max_retries`, `idle_timeout`, `pool_size`).
 - `FulfilApi.with_config` now merges the temporary options over the active configuration instead of replacing it, so a block inherits credentials and other unspecified settings rather than resetting them to their defaults.

data/README.md

@@ -149,6 +149,35 @@ line_items = FulfilApi::Resource.set(model_name: "sale.line").where(["id", "in",
 line_items = FulfilApi::Resource.set(model_name: "sale.line").find_by(["sale.id", "=", 100])
 ```
 
+### Handling Errors
+
+Whenever a request to Fulfil fails, the gem raises a `FulfilApi::HttpError`. Every HTTP status code has its own subclass, named after the status code it represents, so you can rescue the exact failure you care about:
+
+```ruby
+begin
+  FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+rescue FulfilApi::HttpError::TooManyRequests => exception
+  puts exception.message    # => "This user has exceeded an allotted request count. Try again later."
+  puts exception.status_code # => 429
+
+  sleep exception.response_headers["retry-after"].to_i
+  retry
+end
+```
+
+The message is the description reported by Fulfil. The raw response is available through `#response_body`, `#response_headers` and `#status_code`.
+
+To catch anything that went wrong, rescue the base class instead:
+
+```ruby
+rescue FulfilApi::HttpError => exception
+  Rails.logger.error("Fulfil responded with #{exception.status_code}: #{exception.message}")
+```
+
+A request that never reached Fulfil — a connection reset, a DNS failure, a timeout — has no status code to name and raises a `FulfilApi::HttpError` itself.
+
+`FulfilApi::HttpError` inherits from `FulfilApi::Error`, the base class of every error in this gem, so code that already rescues `FulfilApi::Error` keeps working unchanged.
+
 ### Using the 3PL (TPL) Client
 
 The gem also includes a client for Fulfil's [3PL Integration API](https://fulfil-3pl-integration-api.readme.io/reference/getting-started-with-your-api). This is a separate API that allows third-party logistics providers to interact with Fulfil on behalf of a merchant.

data/lib/fulfil_api/client.rb

@@ -167,15 +167,10 @@ module FulfilApi
 
     # @param exception [Faraday::Error] Any error raised by Faraday during the execution
     #   of the HTTP request to the API endpoint.
+    # @raise [FulfilApi::HttpError] The error dedicated to the HTTP status code of the
+    #   response of Fulfil.
     def handle_request_error(exception)
-      raise FulfilApi::Error.new(
-        exception.message,
-        details: {
-          response_body: exception.response_body,
-          response_headers: exception.response_headers,
-          response_status: exception.response_status
-        }
-      )
+      raise FulfilApi::HttpError.from_faraday_error(exception)
     end
 
     # @param method [Symbol, String] The HTTP verb for the HTTP request.

data/lib/fulfil_api/http_error.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module FulfilApi
+  # The {FulfilApi::HttpError} is raised whenever a request to an API endpoint of
+  #   Fulfil fails.
+  #
+  # Every HTTP status code Fulfil can respond with has a dedicated subclass, named
+  #   after the status code it represents. A 429 response raises a
+  #   {FulfilApi::HttpError::TooManyRequests}, a 422 an
+  #   {FulfilApi::HttpError::UnprocessableEntity}, and so on. See {STATUS_CODES} for
+  #   the full list. This lets callers rescue the exact failure they care about
+  #   instead of rescuing everything and inspecting the status code themselves.
+  #
+  # Requests that never reached Fulfil — a connection reset, a DNS failure, a
+  #   timeout — have no status code to name and raise a {FulfilApi::HttpError}.
+  #
+  # @example rescuing one specific HTTP status code
+  #   begin
+  #     FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+  #   rescue FulfilApi::HttpError::TooManyRequests => exception
+  #     sleep exception.response_headers["retry-after"].to_i
+  #     retry
+  #   end
+  #
+  # @example rescuing any failed request
+  #   begin
+  #     FulfilApi::Resource.set(model_name: "sale.sale").find_by(["id", "=", 100])
+  #   rescue FulfilApi::HttpError => exception
+  #     Rails.logger.error("Fulfil responded with #{exception.status_code}: #{exception.message}")
+  #   end
+  #
+  # @note {FulfilApi::HttpError} inherits from {FulfilApi::Error}, so any code that
+  #   already rescues {FulfilApi::Error} keeps catching these exceptions.
+  class HttpError < Error
+    # The keys of an error response of Fulfil that can hold the human readable
+    #   message, in the order they're preferred.
+    #
+    # Fulfil is not consistent in how it reports failures: HTTP level errors carry a
+    #   `description`, application level errors a `message`, and a handful of
+    #   endpoints only return an `error`.
+    MESSAGE_KEYS = %w[description message error].freeze
+
+    # Maps an HTTP status code onto the name of the {FulfilApi::HttpError} subclass
+    #   representing it.
+    STATUS_CODES = {
+      400 => :BadRequest,
+      401 => :Unauthorized,
+      402 => :PaymentRequired,
+      403 => :Forbidden,
+      404 => :NotFound,
+      405 => :MethodNotAllowed,
+      406 => :NotAcceptable,
+      407 => :ProxyAuthenticationRequired,
+      408 => :RequestTimeout,
+      409 => :Conflict,
+      410 => :Gone,
+      411 => :LengthRequired,
+      412 => :PreconditionFailed,
+      413 => :PayloadTooLarge,
+      414 => :UriTooLong,
+      415 => :UnsupportedMediaType,
+      416 => :RangeNotSatisfiable,
+      417 => :ExpectationFailed,
+      418 => :ImATeapot,
+      421 => :MisdirectedRequest,
+      422 => :UnprocessableEntity,
+      423 => :Locked,
+      424 => :FailedDependency,
+      425 => :TooEarly,
+      426 => :UpgradeRequired,
+      428 => :PreconditionRequired,
+      429 => :TooManyRequests,
+      431 => :RequestHeaderFieldsTooLarge,
+      451 => :UnavailableForLegalReasons,
+      500 => :InternalServerError,
+      501 => :NotImplemented,
+      502 => :BadGateway,
+      503 => :ServiceUnavailable,
+      504 => :GatewayTimeout,
+      505 => :HttpVersionNotSupported,
+      506 => :VariantAlsoNegotiates,
+      507 => :InsufficientStorage,
+      508 => :LoopDetected,
+      510 => :NotExtended,
+      511 => :NetworkAuthenticationRequired
+    }.freeze
+
+    # Defines a dedicated exception class for every status code in {STATUS_CODES} and
+    #   indexes them by their status code, so {.for_status_code} can look one up
+    #   without going through {Module#const_get}.
+    CLASSES_BY_STATUS_CODE = STATUS_CODES.transform_values do |class_name|
+      const_set(class_name, Class.new(self))
+    end.freeze
+
+    class << self
+      # Looks up the {FulfilApi::HttpError} subclass representing the given HTTP
+      #   status code.
+      #
+      # @param status_code [Integer, nil] The HTTP status code of the response.
+      # @return [Class<FulfilApi::HttpError>] The subclass for the status code, or
+      #   {FulfilApi::HttpError} itself when the status code is unknown or absent.
+      def for_status_code(status_code)
+        CLASSES_BY_STATUS_CODE.fetch(status_code, HttpError)
+      end
+
+      # Builds the most specific {FulfilApi::HttpError} for the given Faraday exception.
+      #
+      # @param exception [Faraday::Error] Any error raised by Faraday during the
+      #   execution of the HTTP request to the API endpoint.
+      # @return [FulfilApi::HttpError]
+      def from_faraday_error(exception)
+        details = {
+          response_body: exception.response_body,
+          response_headers: exception.response_headers,
+          response_status: exception.response_status
+        }
+
+        for_status_code(exception.response_status).new(
+          message_from(exception.response_body) || exception.message, details: details
+        )
+      end
+
+      private
+
+      # Extracts the human readable error message out of the response body of Fulfil.
+      #
+      # @param response_body [String, Hash, nil] The response body of the API endpoint.
+      # @return [String, nil] The message, or nil when the body holds none. An HTML
+      #   error page and an empty body both yield nil.
+      def message_from(response_body)
+        body = parse(response_body)
+        return if body.nil?
+
+        MESSAGE_KEYS.map { |key| body[key] }.find { |message| message.is_a?(String) && message.present? }
+      end
+
+      # @param response_body [String, Hash, nil] The response body of the API endpoint.
+      # @return [ActiveSupport::HashWithIndifferentAccess, nil]
+      def parse(response_body)
+        return response_body.with_indifferent_access if response_body.is_a?(Hash)
+        return if response_body.blank?
+
+        parsed_body = JSON.parse(response_body)
+        parsed_body.with_indifferent_access if parsed_body.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Unlike {FulfilApi::Error}, the message is returned as-is. The name of the
+    #   exception class already tells you what went wrong, so prefixing it only gets
+    #   in the way of the description reported by Fulfil.
+    #
+    # @note {StandardError#message} delegates to {StandardError#to_s}, which still
+    #   holds the message passed to the constructor.
+    #
+    # @return [String]
+    def message
+      to_s
+    end
+
+    # @return [String, Hash, nil] The raw response body of the API endpoint of Fulfil.
+    def response_body
+      details&.dig(:response_body)
+    end
+
+    # @return [Hash, nil] The response headers of the API endpoint of Fulfil.
+    def response_headers
+      details&.dig(:response_headers)
+    end
+
+    # @return [Integer, nil] The HTTP status code of the response, or nil when the
+    #   request never reached Fulfil.
+    def status_code
+      details&.dig(:response_status)
+    end
+  end
+end

data/lib/fulfil_api/relation/batchable.rb

@@ -49,7 +49,7 @@ module FulfilApi
       # @yield [FulfilApi::Relation] Yields FulfilApi::Relation
       #   objects to work with a batch of records.
       # @return [FulfilApi::Relation]
-      def in_batches(of: 500, retries: :unlimited) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+      def in_batches(of: 500, retries: :unlimited) # rubocop:disable Metrics/MethodLength
         current_retry = 0
         current_offset = request_offset.presence || 0
         batch_size = of
@@ -64,18 +64,14 @@ module FulfilApi
 
           current_offset += 1
           current_retry = 0 # Reset the retries back to the default
-        rescue FulfilApi::Error => e
-          if e.details[:response_status] == 429
-            if retries != :unlimited && current_retry > retries
-              raise RetryLimitExceeded, "the maximum number of #{retries} retries has been reached."
-            end
-
-            current_retry += 1
-            sleep 0.25
-            retry
+        rescue FulfilApi::HttpError::TooManyRequests
+          if retries != :unlimited && current_retry > retries
+            raise RetryLimitExceeded, "the maximum number of #{retries} retries has been reached."
           end
 
-          raise e
+          current_retry += 1
+          sleep 0.25
+          retry
         end
 
         self

data/lib/fulfil_api/tpl_client.rb

@@ -182,15 +182,10 @@ module FulfilApi
 
     # @param exception [Faraday::Error] Any error raised by Faraday during the execution
     #   of the HTTP request to the API endpoint.
+    # @raise [FulfilApi::HttpError] The error dedicated to the HTTP status code of the
+    #   response of Fulfil.
     def handle_request_error(exception)
-      raise FulfilApi::Error.new(
-        exception.message,
-        details: {
-          response_body: exception.response_body,
-          response_headers: exception.response_headers,
-          response_status: exception.response_status
-        }
-      )
+      raise FulfilApi::HttpError.from_faraday_error(exception)
     end
 
     # @param method [Symbol, String] The HTTP verb for the HTTP request.

data/lib/fulfil_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FulfilApi
-  VERSION = "0.7.0"
+  VERSION = "0.7.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fulfil_api
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Stefan Vermaas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -86,6 +86,7 @@ files:
 - lib/fulfil_api/configuration.rb
 - lib/fulfil_api/customer_shipment.rb
 - lib/fulfil_api/error.rb
+- lib/fulfil_api/http_error.rb
 - lib/fulfil_api/relation.rb
 - lib/fulfil_api/relation/batchable.rb
 - lib/fulfil_api/relation/countable.rb