feat: opt-in HTTP error taxonomy with overridable mapping (#216)

Adds an opt-in (config.raise_error_taxonomy, default false) typed NxtHttpClient::Error taxonomy for HTTP status + network/code-0 failures, a map_error DSL to override the mapping per client, a json_response empty/204-body guard, credential redaction in Error#to_h, and Sentry reporting via set_context. Backwards compatible (taxonomy off by default). HELDENPMI-132.

Author: mitnal

CHANGELOG.md

@@ -1,3 +1,23 @@
+# v2.2.0 2026-06-15
+- Report HTTP error details to Sentry via the structured `set_context('http_error', …)` instead of the
+  deprecated `set_extras(http_error_details: …)`. (Typhoeus is not auto-instrumented by Sentry, so the gem
+  attaches this itself.)
+- `Error#to_h` now redacts the `Authorization` header and basic-auth `userpwd` (it is sent to Sentry).
+- `json_response` now returns `nil` for an empty/204 body instead of raising `JSON::ParserError`.
+- Add an opt-in error taxonomy under `NxtHttpClient::Error`. With `config.raise_error_taxonomy = true` the client
+  raises a typed subclass for an unhandled 4xx/5xx/code-0 response instead of returning it:
+  - HTTP status: `ClientError` with `BadRequest` (400), `Unauthorized` (401), `Forbidden` (403),
+    `NotFound` (404), `UnprocessableEntity` (422), `TooManyRequests` (429); `ServerError` (5xx).
+  - Network (`return_code`-mapped code-0): `NetworkError` with `Timeout`, `ConnectionFailed`,
+    `NameResolutionError`, `TlsError`; `CertificateError` (cert verification — a sibling, not a child).
+- Retryable errors share base classes — `retry_on NxtHttpClient::Error::NetworkError, NxtHttpClient::Error::ServerError`.
+  4xx, `CertificateError` and 429 are excluded (429 retry policy is left to consumers).
+- `map_error(status, klass)` DSL to override the mapping per client (e.g. a domain `ValidationFailed` that
+  parses the body); inherited by subclasses.
+- `config.raise_error_taxonomy` defaults to `false`, so the upgrade is backwards compatible — existing behavior
+  (and `raise_response_errors`) is unchanged until you opt in. A consumer's own `on(<code>)`/`on(:error)`/
+  `on(:timed_out)` callback always takes precedence over the taxonomy.
+
 # v2.1.0 2024-06-05
 - Bump dependencies
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nxt_http_client (2.1.1)
+    nxt_http_client (2.2.0)
       activesupport
       nxt_registry
       typhoeus

README.md

@@ -48,7 +48,7 @@ class UserServiceClient < NxtHttpClient::Client
     # Note: This error handler is set by default when you use 
     # config.raise_response_errors = true
     handler.on(:error) do |response|
-      Sentry.set_extras(http_error_details: error.to_h)
+      Sentry.set_context('http_error', error.to_h)
       raise StandardError, "I can't handle this: #{response.code}"
     end
   end
@@ -118,12 +118,16 @@ Register your default request options on the class level. Available options are:
 - `base_url=`
 - `x_request_id_proc=`
 - `json_request=`: Shorthand to set the Content-Type request header to JSON and automatically convert request bodies to JSON
-- `json_response=`: Shorthand to set the Accept request header and automatically convert success response bodies to JSON
-- `raise_response_errors=`: Makes the client raise a `NxtHttpClient::Error` for a non-success response. 
-  You can also do this manually by setting a response_handler.
+- `json_response=`: Shorthand to set the Accept request header and automatically convert success response bodies to JSON (an empty/204 body becomes `nil`)
+- `raise_response_errors=`: Makes the client raise a generic `NxtHttpClient::Error` for a non-success response.
+  Superseded by `raise_error_taxonomy` (which raises typed errors and takes precedence when both are set); kept for
+  backward compatibility.
+- `raise_error_taxonomy=`: Defaults to `false`. Opt in to raise the mapped `NxtHttpClient::Error` taxonomy
+  (`ClientError`/`ServerError`/`NetworkError` subclasses) on an unhandled 4xx/5xx/code-0 response instead of
+  returning it. See [Error taxonomy](#error-taxonomy).
 - `bearer_auth=`: Set a bearer token to be sent in the Authorization header
 - `basic_auth=`: Pass a Hash containing `:username` and `:password`, to be sent as Basic credentials in the Authorization header
-- `timeouts(total:, connect: nil)`: Configure timeouts
+- `timeout_seconds(total:, connect: nil)`: Configure timeouts
 
 ### response_handler
 
@@ -215,13 +219,84 @@ To set a timeout, use the `timeout_seconds` config method:
 configure do |config|
   config.timeout_seconds(total: 10)
   # You can also set a connect timeout
-  config.timeout_seconds(total: 10, connecttimeout: 2)
+  config.timeout_seconds(total: 10, connect: 2)
 end
 ```
 
 NxtHttpClient::Error exposes the `timed_out?` method from `Typhoeus::Response`, so you can check if an error is raised due to a timeout. 
 This is useful when setting a custom timeout value in your configuration.
 
+### Error taxonomy
+
+Set `config.raise_error_taxonomy = true` and the client raises a typed subclass of `NxtHttpClient::Error` for an
+unhandled 4xx, 5xx, or code-0 (network) response, so you no longer need to hand-roll per-status
+`on(400)`/`on(422)`/`on(5xx)`/`on(0)` handlers just to get a usable taxonomy. (3xx and other codes are returned
+as before.) It is **off by default** (the client returns the response); all classes inherit from
+`NxtHttpClient::Error`, so existing `rescue NxtHttpClient::Error` handlers keep working.
+
+**HTTP status:**
+
+| status        | class                                       | retryable? |
+|---------------|---------------------------------------------|------------|
+| 400           | `NxtHttpClient::Error::BadRequest`          | no         |
+| 401           | `NxtHttpClient::Error::Unauthorized`        | no         |
+| 403           | `NxtHttpClient::Error::Forbidden`           | no         |
+| 404           | `NxtHttpClient::Error::NotFound`            | no         |
+| 422           | `NxtHttpClient::Error::UnprocessableEntity` | no         |
+| 429           | `NxtHttpClient::Error::TooManyRequests`     | up to you  |
+| other 4xx     | `NxtHttpClient::Error::ClientError`         | no         |
+| 5xx           | `NxtHttpClient::Error::ServerError`         | yes        |
+
+**Network / code 0.** Typhoeus/libcurl surfaces network failures and timeouts as a response with HTTP **code 0**
+(no response received); the real cause lives in libcurl's `return_code`:
+
+| libcurl `return_code`                              | class                                       | retryable? |
+|----------------------------------------------------|---------------------------------------------|------------|
+| `:operation_timedout`                              | `NxtHttpClient::Error::Timeout`             | yes        |
+| `:couldnt_connect`                                 | `NxtHttpClient::Error::ConnectionFailed`    | yes        |
+| `:couldnt_resolve_host` / `:couldnt_resolve_proxy` | `NxtHttpClient::Error::NameResolutionError` | yes        |
+| `:ssl_connect_error` and other non-cert `:ssl_*`   | `NxtHttpClient::Error::TlsError`            | yes        |
+| any other code-0                                   | `NxtHttpClient::Error::NetworkError`        | yes        |
+| cert verification (`:peer_failed_verification`, …)  | `NxtHttpClient::Error::CertificateError`    | no         |
+
+#### Retrying
+
+The retryable errors share two base classes, so a job retries them in one place:
+
+```ruby
+retry_on NxtHttpClient::Error::NetworkError, NxtHttpClient::Error::ServerError
+```
+
+`ClientError` (4xx) is not retried — those are caller mistakes. `CertificateError` is a **sibling** of `NetworkError`
+(not a child), so it is excluded from `retry_on NetworkError` — a failed cert/CA verification is permanent.
+`TooManyRequests` (429) is left out of the retryable set; add your own `retry_on NxtHttpClient::Error::TooManyRequests`
+(ideally honoring `Retry-After`) if you want it.
+
+#### Precedence and opting out
+
+A consumer's own `on(<code>)` / `on(:error)` / `on(:timed_out)` callback always takes precedence; the raise only
+fires when nothing else handled the response. So you can enable the taxonomy for retries yet still handle, say, a
+404 inline with your own `on(404)`.
+
+#### Domain-typed errors
+
+Map a status to your own error class with `map_error` to get a domain error that parses the response body. It is
+inherited by subclasses and overrides the default for that status. `map_error` only takes effect when
+`raise_error_taxonomy` is enabled — it customizes the taxonomy, it does not enable raising on its own:
+
+```ruby
+class MyService::Client < NxtHttpClient::Client
+  configure { |config| config.raise_error_taxonomy = true }
+  map_error 422, MyService::Error::ValidationFailed
+end
+
+class MyService::Error::ValidationFailed < NxtHttpClient::Error
+  def default_message
+    body.dig('errors', 0, 'detail') # `body` parses JSON response bodies for you
+  end
+end
+```
+
 ### Logging
 
 NxtHttpClient also comes with a log method on the class level that you can pass a proc if you want to log your request.

lib/nxt_http_client/client.rb

@@ -144,7 +144,25 @@ def url_without_duplicated_hashes(url)
 
     def callback_or_response(response, response_handler)
       callback = response_handler.callback_for_response(response)
-      callback && instance_exec(response, &callback) || response
+      return instance_exec(response, &callback) || response if callback
+
+      return raise_mapped_error(response) if raise_mapped_error?(response)
+
+      response
+    end
+
+    # Reached only when no consumer callback matched, so a consumer on(<code>)/on(:error) keeps precedence.
+    def raise_mapped_error?(response)
+      return false unless config.raise_error_taxonomy
+
+      code = response.code.to_i
+      code.zero? || (400..599).cover?(code)
+    end
+
+    def raise_mapped_error(response)
+      error = self.class.error_class_for(response).new(response)
+      ::Sentry.set_context('http_error', error.to_h) if defined?(::Sentry)
+      raise error
     end
 
     def build_response_handler(handler, &block)
@@ -153,17 +171,20 @@ def build_response_handler(handler, &block)
       if config.json_response
         response_handler.configure do |handler|
           handler.on(:success) do |response|
-            response.define_singleton_method(:body) { JSON(response.response_body) }
+            # nil for a blank/204 body — parsing "" would raise JSON::ParserError
+            response.define_singleton_method(:body) { response.response_body.presence && JSON(response.response_body) }
             response
           end
         end
       end
 
-      if config.raise_response_errors
+      # Legacy generic-error raising. Superseded by raise_error_taxonomy (typed), which takes precedence here
+      # via the callback_or_response fallback — so don't also register this shadowing on(:error) handler.
+      if config.raise_response_errors && !config.raise_error_taxonomy
         response_handler.configure do |handler|
           handler.on(:error) do |response|
             error = NxtHttpClient::Error.new(response)
-            ::Sentry.set_extras(http_error_details: error.to_h) if defined?(::Sentry)
+            ::Sentry.set_context('http_error', error.to_h) if defined?(::Sentry)
             raise error
           end
         end

lib/nxt_http_client/client_dsl.rb

@@ -52,6 +52,24 @@ def response_handler(handler = Undefined.new, &block)
       @response_handler
     end
 
+    # Override the taxonomy's error class for a status, e.g. `map_error 422, MyService::ValidationFailed`.
+    # Only takes effect when config.raise_error_taxonomy is enabled.
+    def map_error(status, error_class)
+      unless error_class.is_a?(Class) && error_class <= NxtHttpClient::Error
+        raise ArgumentError, "#{error_class.inspect} must be a subclass of NxtHttpClient::Error"
+      end
+
+      error_map[Integer(status)] = error_class
+    end
+
+    def error_map
+      @error_map ||= dup_option_from_ancestor(:@error_map) { {} }
+    end
+
+    def error_class_for(response)
+      error_map[response.code.to_i] || NxtHttpClient::Error.error_class_for(response)
+    end
+
     private
 
     def client_ancestors

lib/nxt_http_client/config.rb

@@ -8,7 +8,10 @@ module NxtHttpClient
     json_request: false,
     # Helper to set the Accept request header and automatically convert success response bodies to JSON
     json_response: false,
-    raise_response_errors: false,
+    raise_response_errors: false, # Legacy: raises a generic NxtHttpClient::Error. Superseded by raise_error_taxonomy.
+    # Opt in (default false) to raise the mapped NxtHttpClient::Error taxonomy on an unhandled
+    # 4xx/5xx/code-0 response instead of returning it. See README "Error taxonomy".
+    raise_error_taxonomy: false,
 
     bearer_auth: nil,
     basic_auth: nil,

lib/nxt_http_client/error.rb

@@ -1,5 +1,49 @@
 module NxtHttpClient
   class Error < StandardError
+    # Cert/trust failures — mapped to non-retryable CertificateError, kept out of the generic TlsError.
+    CERTIFICATE_RETURN_CODES = %i[
+      peer_failed_verification ssl_certproblem ssl_cacert_badfile ssl_issuer_error ssl_crl_badfile
+    ].freeze
+
+    REDACTED = '[REDACTED]'
+    SENSITIVE_HEADERS = %w[Authorization Proxy-Authorization].freeze
+
+    def self.from_response(response, message = nil)
+      error_class_for(response).new(response, message)
+    end
+
+    def self.error_class_for(response)
+      code = response.respond_to?(:code) ? response.code.to_i : 0
+      return network_error_class(response.respond_to?(:return_code) ? response.return_code : nil) if code.zero?
+
+      status_error_class(code)
+    end
+
+    def self.status_error_class(code)
+      case code
+      when 400 then BadRequest
+      when 401 then Unauthorized
+      when 403 then Forbidden
+      when 404 then NotFound
+      when 422 then UnprocessableEntity
+      when 429 then TooManyRequests
+      when 400..499 then ClientError
+      when 500..599 then ServerError
+      else self # 3xx etc. → base Error
+      end
+    end
+
+    def self.network_error_class(return_code)
+      case return_code
+      when :operation_timedout then Timeout
+      when :couldnt_connect then ConnectionFailed
+      when :couldnt_resolve_host, :couldnt_resolve_proxy then NameResolutionError
+      when *CERTIFICATE_RETURN_CODES then CertificateError
+      else
+        return_code.to_s.include?('ssl') ? TlsError : NetworkError
+      end
+    end
+
     def initialize(response, message = nil)
       @response = response.blank? ? Typhoeus::Response.new : response
       @id = SecureRandom.uuid
@@ -22,9 +66,9 @@ def to_h
         id: id,
         url: url,
         response_code: response_code,
-        request_options: request_options,
+        request_options: redact_credentials(request_options),
         response_headers: response_headers,
-        request_headers: request_headers,
+        request_headers: redact_authorization(request_headers),
         body: body,
         x_request_id: x_request_id
       }
@@ -77,5 +121,46 @@ def response_headers
     def response_content_type
       response_headers['Content-Type']
     end
+
+    private
+
+    # Keep Authorization tokens / basic-auth creds out of serialized output (to_h reaches Sentry).
+    def redact_credentials(options)
+      options = options.merge('userpwd' => REDACTED) if options.key?('userpwd')
+      return options unless options['headers'].respond_to?(:key?)
+
+      options.merge('headers' => redact_authorization(options['headers']))
+    end
+
+    def redact_authorization(headers)
+      return headers unless headers.respond_to?(:keys)
+
+      # HTTP header names are case-insensitive, and HashWithIndifferentAccess does not normalize case.
+      sensitive = headers.keys.select { |key| SENSITIVE_HEADERS.any? { |name| key.to_s.casecmp?(name) } }
+      return headers if sensitive.empty?
+
+      headers.merge(sensitive.index_with { REDACTED })
+    end
+
+    public
+
+    class ClientError < self; end
+    class BadRequest < ClientError; end           # 400
+    class Unauthorized < ClientError; end          # 401
+    class Forbidden < ClientError; end             # 403
+    class NotFound < ClientError; end              # 404
+    class UnprocessableEntity < ClientError; end   # 422
+    class TooManyRequests < ClientError; end       # 429
+
+    class ServerError < self; end
+
+    class NetworkError < self; end                # code 0 (no HTTP response)
+    class Timeout < NetworkError; end             # :operation_timedout
+    class ConnectionFailed < NetworkError; end    # :couldnt_connect
+    class NameResolutionError < NetworkError; end # :couldnt_resolve_host / :couldnt_resolve_proxy
+    class TlsError < NetworkError; end            # :ssl_connect_error and other non-cert :ssl_*
+
+    # Sibling of NetworkError, not a child, so it's excluded from `retry_on NetworkError`.
+    class CertificateError < self; end
   end
 end

lib/nxt_http_client/version.rb

@@ -1,3 +1,3 @@
 module NxtHttpClient
-  VERSION = "2.1.1"
+  VERSION = "2.2.0"
 end