[mitnal]

Issue Link: HELDENPMI-132 (supersedes HELDENPMI-131)

Adds an opt-in typed error taxonomy under NxtHttpClient::Error, so consumers stop hand-rolling the identical on(400)/on(401)/on(404)/on(422)/on(5xx)/on(0) boilerplate just to get a usable taxonomy for discard_on/retry_on and Sentry grouping.

Enabled with config.raise_error_taxonomy = true; off by default, so a plain gem bump is fully backward compatible — existing behavior (and raise_response_errors) is unchanged until a consumer opts in (the per-consumer rollout step where its boilerplate is deleted). Supersedes the original network-only scope (HELDENPMI-131); the interim NxtHttpClient::TransientError marker is removed before it ships.

Taxonomy (all inherit NxtHttpClient::Error)

HTTP status:

status	class	retryable?
400	Error::BadRequest	no
401	Error::Unauthorized	no
403	Error::Forbidden	no
404	Error::NotFound	no
422	Error::UnprocessableEntity	no
429	Error::TooManyRequests	up to consumer
other 4xx	Error::ClientError	no
5xx	Error::ServerError	yes

Network / code 0 (return_code-mapped):

return_code	class	retryable?
:operation_timedout	Error::Timeout	yes
:couldnt_connect	Error::ConnectionFailed	yes
:couldnt_resolve_host / _proxy	Error::NameResolutionError	yes
:ssl_connect_error + non-cert :ssl_*	Error::TlsError	yes
any other code-0	Error::NetworkError	yes
cert verification (:peer_failed_verification, …)	Error::CertificateError	no

Retry pattern

retry_on NxtHttpClient::Error::NetworkError, NxtHttpClient::Error::ServerError

4xx (ClientError) not retried. CertificateError is a sibling of NetworkError (not a child) → excluded. TooManyRequests/429 left to consumers.

Overridable mapping

class MyService::Client < NxtHttpClient::Client
  map_error 422, MyService::Error::ValidationFailed  # raises a domain error that parses the body
end

Inherited by subclasses; overrides the default for that status.

Precedence

The taxonomy raises only via the callback_or_response fallback — never an on(:error) registration (which would collide with a consumer's own on(:error)). So a consumer's on(<code>)/on(:error)/on(:timed_out) always wins; you can enable the taxonomy for retries yet still handle e.g. a 404 inline.

Backward compatibility

• Off by default (raise_error_taxonomy = false) → no behavior change on upgrade; raise_response_errors keeps raising the generic NxtHttpClient::Error.
• ✅ rescue NxtHttpClient::Error / is_a? — all subclasses inherit from it.
• ⚠️ Once enabled: exact-class checks (e.class ==) and error-message strings change → Sentry fingerprints regroup.

Not in this PR (follow-ups)

• Release to GitHub Packages (2.2.0); bump consumers and set raise_error_taxonomy = true.
• Delete per-status response_handler boilerplate; delete the user-service local NxtHttpClient::TransientError initializer (HELDENPMI-130).
• Switch concerns to retry_on NetworkError, ServerError across admin-panel / claims / payment / insurance.

Tests

Full suite green (84 examples): status→class + return_code→class mapping, opt-in default-off, raising when enabled, consumer-callback precedence, and overridable map_error.

[Copilot]

Pull request overview

Adds an opt-in, typed NxtHttpClient::Error taxonomy (HTTP status + network/code-0) to standardize retry/discard handling and error grouping, while keeping existing behavior unchanged unless explicitly enabled.

Changes:

• Introduces NxtHttpClient::Error.from_response + subclass taxonomy (ClientError/ServerError/NetworkError and specific status/return_code subclasses).
• Adds config.raise_error_taxonomy and a map_error(status, klass) DSL override, with taxonomy raising occurring only as a fallback when no consumer callback handled the response.
• Adjusts JSON response parsing to return nil for empty/204 bodies; bumps version/changelog and adds specs for mappings + opt-in behavior.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
spec/error_spec.rb	Adds unit coverage for response→error-class mapping and retryable hierarchy expectations.
spec/configuration_spec.rb	Adds coverage for 204 JSON body handling and taxonomy opt-in raising/precedence/map overrides.
README.md	Documents new raise_error_taxonomy behavior, retry pattern, and map_error; notes 204 JSON body behavior.
lib/nxt_http_client/version.rb	Bumps gem version to 2.2.0.
lib/nxt_http_client/error.rb	Implements error taxonomy classes + mapping logic (status_error_class / network_error_class).
lib/nxt_http_client/config.rb	Adds raise_error_taxonomy config default + documentation comments.
lib/nxt_http_client/client.rb	Implements fallback raising of mapped errors; prevents legacy raise_response_errors handler when taxonomy enabled; makes JSON parsing nil-safe for empty bodies.
lib/nxt_http_client/client_dsl.rb	Adds map_error + per-client error mapping inheritance via error_map.
Gemfile.lock	Updates lockfile version to 2.2.0.
CHANGELOG.md	Documents 2.2.0 changes (taxonomy + 204 JSON handling).

Comments suppressed due to low confidence (1)

lib/nxt_http_client/client.rb:188

• Same concern as the taxonomy path: error.to_h includes request headers/options and body, which may contain secrets (Authorization/basic auth) and PII. Even if Sentry has server-side scrubbing, it’s safer to avoid sending these fields by default from the client library.

          handler.on(:error) do |response|
            error = NxtHttpClient::Error.new(response)
            ::Sentry.set_extras(http_error_details: error.to_h) if defined?(::Sentry)
            raise error

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[clementbruno]

Since the method now returns response at the end by default do we still need the || response part here?

Are there situations where we would expect instance_exec(response, &callback) to return nil and would want to avoid returning it?

[mitnal]

We still need it to be able to continue having callbacks without a response returning the response.