conexa 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71329999c6d13c4e935ef1e37a8eca6df5811c44d0326184cc1676d31fb199b
-  data.tar.gz: c6f6946375a05712ed7d952a4314738e86a2429bf3a249e269d2fd40b254c11f
+  metadata.gz: 1ff60656e2731455f658e616416581ede3b7a062e184097f756bcaaca9b523d4
+  data.tar.gz: d3c3a28eb846199bfebfbe963b160af18baab1be9fcfeee2382466a8916c145a
 SHA512:
-  metadata.gz: 13fc7859937cd156cd8ae68b78d6c303b62460d4f6e682f270f58927e87c8a99e29e7d43a4814318b53ed5c5e20ce5e0ea3892d46db8d4d08147e9aea79a690e
-  data.tar.gz: c1ae89758b0cea23df6c5f5cc16895c060baef04da9a31fefd58eb7ac9c7ba1b1483dfc44b81c00ddfb592cada2e34cace170237e5f298b3ea8b3217572bd1c9
+  metadata.gz: 3108d62cff165810c56ae8e5ba738b54ebfa223995617cc7099abebd6511db45a1bab061f7c99df229512ef3004da6d05a0cab623e9662bed464606b9322a1dd
+  data.tar.gz: 1c15d0d6ed78d606e5cfb5a40b56399ab05dacaf8b28bd6562c12ec6f1cae40a87bf3d00e2f09140de061ab36a411eefd63cc2361ae3208907241ec51c23f89e

data/CHANGELOG.md

@@ -7,6 +7,211 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-11
+
+Aligns the gem with the published API v2 contract. **0.1.1 is broken**:
+`Charge.settle` and `Contract.end_contract` 404 against a live tenant, and a
+successful write that answers with an empty body raises `NoMethodError` after
+the operation has already taken effect — in a billing integration that invites a
+retry. Upgrading is strongly recommended.
+
+Every fix below was verified against `docs/postman-collection.json`, Conexa's own
+published documentation, and is now enforced by
+`spec/contract/api_contract_spec.rb`.
+
+### Fixed
+- **Empty response bodies no longer raise, anywhere.** `Request#run` returns `{}`
+  for an empty, whitespace or `null` body at any status. With the Oj adapter
+  `MultiJson.decode("")` returns `nil` without raising, so the previous
+  `rescue MultiJson::ParseError` / `204` guard never fired — even a documented
+  `204` success (`PATCH /charge/settle/:id`) raised `NoMethodError`, which is not
+  a `Conexa::ConexaError` and escaped `rescue Conexa::ConexaError`.
+
+  `ConexaObject#update` treats anything carrying no attributes as "nothing to
+  merge" — `nil`, `{}`, and the arrays and scalars `Request#run` also produces —
+  and `Model#create` does the same. Fixing `Request#run` alone was not enough:
+  `Model#save` and `#destroy` fed the result straight into `update`, so **every**
+  resource's generic CRUD still raised `NoMethodError` on a documented `204`
+  (`DELETE /sale/:id` among them). Only the three action methods were safe, and
+  only because they discard their return value.
+- **A write answering `200 {}` no longer wipes the object.** `update` removes
+  every attribute absent from the incoming hash, which is right for a full
+  refresh and destructive for an empty write response — it cleared the whole
+  object, primary key included, and reported success.
+- **`Model#save` guards a blank id**, as `#destroy` already did. Without it an
+  id-less object issued `PATCH /customer/` instead of failing fast.
+- **`Result#next_page` raises a `Conexa` error** when pagination carries no
+  `limit`, instead of `TypeError` from `nil + Integer`, and survives a
+  non-marshallable filter in the original query.
+- **`Conexa::ValidationError` is usable.** It rendered as the bare string
+  `"Conexa::ValidationError"` and `#to_h` raised `NoMethodError`. It is only
+  reachable for an error body with no `message` key — which no documented
+  response has — but it now reports what actually arrived.
+- **Exception messages read as prose.** The old format appended a dangling
+  `"=> Erros: "` to the 75 documented responses that carry no `errors` array, and
+  dumped Ruby's `#inspect` of an array of hashes for the ones that do. It now
+  uses the same normalisation as `#api_error_messages`:
+  `422 … => It was not possible to process your request — CHARGE_11: Only open charges can be settled.`
+- **Error bodies that are not JSON objects no longer raise `TypeError`.** An
+  array or scalar error body reached `parsed_error['message']` and blew up inside
+  the error handler.
+- **`Request#run` tolerates a top-level array or scalar body.** Defensive: every
+  list endpoint probed on 2026-08-12 used the `{data, pagination}` envelope, so
+  this shape has not been observed in the wild — it removes a crash class rather
+  than fixing a seen failure.
+- **Action endpoints use the documented verb.** `Charge#settle`,
+  `Contract#end_contract` and `RecurringSale#end_recurring_sale` send `PATCH`;
+  `POST` 404s.
+- **`Conexa::Company.all` requests the documented `/companies`.** `Model#url`
+  pluralizes by appending `"s"`, which produced `/companys`. A read-only probe of
+  a live tenant on 2026-08-12 showed the API routes **both** spellings, so this
+  was an undocumented path that worked rather than the 404 first reported — the
+  override stands because an undocumented alias can vanish without notice, but
+  nothing was broken by it.
+- **Nested arrays are camelized.** `Util.camelize_hash` treated an `Array` as a
+  scalar, so snake_case keys inside arrays of objects were sent untouched and
+  rejected. Affects `complementaryServices`, `productQuotas`, `devices`,
+  `extraFields`, `bookingModels`, `visitors` and `costCenters` — ten documented
+  endpoints across seven resources.
+- **`page`/`size` are converted to `limit`/`offset`** instead of being sent. The
+  API validates `page` and then ignores it, always answering `offset: 0`, so a
+  loop driven by `hasNext` never terminated and silently re-yielded the same
+  batch. Non-positive or non-integer values now raise `Conexa::RequestError`.
+- **`Model#id` falls back to `attributes["id"]` again.** `primary_key_attribute`
+  aliased `#id` onto the resource key, making the documented fallback dead code —
+  write endpoints answer with `{"id": N}`, which is what `Model#create` reads.
+- **`ResponseError` no longer raises `NoMethodError` on malformed bodies.** It was
+  handed a `RestClient::Response`, which has no `#message`.
+- **A broken connection raises `Conexa::ConnectionError`** (issue #11). The
+  `rescue RestClient::ServerBrokeConnection` clause was unreachable —
+  `ServerBrokeConnection` subclasses `RestClient::Exception`, so the broader
+  clause listed above it always matched first, then tried to decode a `nil`
+  `http_body` and raised `NoMethodError` from inside the error handler.
+  Connection-level failures are now rescued first: `SocketError`,
+  `ServerBrokeConnection`, `SSLCertificateNotVerified` and
+  `RestClient::Exceptions::Timeout`. A real HTTP 408 stays in the response
+  taxonomy, since `RestClient::RequestTimeout` is a *superclass* of
+  `Exceptions::Timeout`.
+- **An unusable id raises `Conexa::RequestError`, not `URI::InvalidURIError`**
+  (issue #12). `find(" 123 ")` leaked a URI error from inside RestClient, outside
+  the `Conexa::ConexaError` hierarchy. Surrounding whitespace is now stripped, and
+  `Request#full_api_url` validates the URL it builds.
+- **`RecurringSale#end_recurring_sale` sends the documented `date`.** The verb was
+  corrected but the field was not, so `end_date:` still went out as the rejected
+  `endDate`, and its YARD named that field as the example. It now shares
+  `Util.normalize_end_date_param` with `Contract`, and gains a `set_end_date`
+  alias for symmetry.
+- `README.md` configured a non-existent `config.subdomain`; the quick start now
+  runs.
+- `lib/conexa/resources/supplier.rb` shipped as `0600`, breaking `require` on a
+  shared install.
+
+- **`Conexa::CreditCard` is write-only.** API v2 exposes no read for it: `GET
+  /creditCard` answers "Unable to resolve the request" and `GET /creditCard/:id`
+  "unable to find the requested action" — neither is the permission wording the
+  API uses for a resource an account cannot see. `all`/`find`/`find_by` and their
+  aliases now raise `Conexa::RequestError` explaining that, instead of a bare
+  `NotFound` reading as "no such card", and `#create` skips `Model#create`'s
+  re-fetch. The integration spec that asserted those reads worked — against
+  stubs of endpoints that do not exist — was rewritten.
+- **Listings always answer with a `Conexa::Result`.** An empty body yielded `nil`
+  and a bare-array body an `Array`, so `.data`/`.pagination`/`.next_page` failed
+  far from the cause.
+- **`Model#fetch` raises instead of silently keeping stale attributes** when the
+  refresh comes back with no body. The nil-guard that makes an empty *write*
+  response harmless must not make an empty *read* look successful.
+- **`Result#has_next?` returns a boolean**, not `nil`, when there is no
+  pagination at all.
+
+### Added
+- **Read-only mode.** `config.read_only = true`, `CONEXA_READ_ONLY=1`, or a
+  `Conexa.read_only { ... }` block. Any non-`GET` request raises
+  `Conexa::ReadOnlyError` before it leaves the process. Settling a charge moves
+  money and can issue an NF-e, so this is a guard worth having when you only mean
+  to read.
+
+  The exemption for `POST /auth` is matched on the **path**, not on the caller's
+  `auth:` flag — `Request.auth` is public, so keying it off the flag would have
+  let any write opt out of the guard. `CONEXA_READ_ONLY` is consulted at each
+  check rather than captured at configure time, and an unrecognised value warns
+  instead of silently failing open. The block form is fiber-local and does not
+  reach a `Thread` or `Fiber` spawned inside it — documented in the READMEs; use
+  `config.read_only` for concurrent work.
+- **`ResponseError#api_errors`, `#api_error_codes`, `#api_error_messages`,
+  `#api_response`** — normalise the API's two error shapes (`{field, messages}`
+  and `{code, message}`). Consumers that only handled the first rendered
+  business-rule errors as blank strings, which is how
+  `CONTRACT_RECURRING_SALE_10` stayed invisible through eight attempts.
+  `api_error_codes` makes documented codes such as `CHARGE_11` usable as control
+  flow — the way to tell an already-settled charge from a real failure.
+- **`Contract#set_end_date`** (with `end_contract` kept as an alias), taking the
+  documented `date:`, `reason_id:` and `unlink_customer:`. The endpoint both
+  closes a contract and amends its end date, and a future date on a closed
+  contract reopens it.
+- **Contract-level test coverage**: `spec/contract/api_contract_spec.rb` checks
+  every emitted URL and action verb against the vendored collection, with an
+  explicit allowlist and a guard that fails when an endpoint is added without one.
+  `spec/support/request_capture.rb` asserts the request the gem actually emits
+  rather than stubbing the expected one.
+- `verify_partial_doubles = true`.
+- YARD documentation of `POST /contract`'s fields, including the conditional
+  `due_day` rule and the atomic `firstOccurrenceSettleRetroactive` flow.
+
+### Changed
+- **Breaking**: `end_contract` sends the documented `date`; `end_date:` still
+  works as a deprecated alias and will be removed in 0.3.0.
+- **Breaking**: writes that answer with an empty body now return normally instead
+  of raising. Callers treating the exception as a signal must be reviewed.
+- **Breaking**: `page`/`size` no longer reach the wire.
+- Minimum Ruby is now **3.1** (was 2.6, never tested below 3.1). CI covers
+  3.1–3.4.
+- `rest-client` and `multi_json` are version-bounded. `multi_json`'s adapter
+  behaviour is load-bearing — the empty-body defect exists because Oj returns
+  `nil` rather than raising.
+- The gemspec's development dependencies move to bundler's `:test` group, and
+  `debug`/`byebug` to an optional `:development` group, so a native-extension
+  failure in `io-console` can no longer stop `bundle exec rspec`.
+- **The packaged gem is 48 KB, down from 163 KB.** `spec.files` shipped the whole
+  repository — including `docs/postman-collection.json` (1.7 MB) — against 58 KB
+  of library code. It now ships `lib/` and the documentation only.
+- **`Gemfile.lock` is no longer committed**, as is conventional for a gem: a
+  pinned lockfile defeats testing against the range the gemspec allows, and CI
+  had been working around it by deleting the file before `bundle install`.
+- **`rake` passes again.** The default task is `spec` + `rubocop`, and RuboCop's
+  ~2000 pre-existing offences made it fail, which is why CI ran lint with
+  `continue-on-error`. A generated `.rubocop_todo.yml` grandfathers them, so new
+  code is genuinely linted and CI can gate on it.
+- `rake spec:all` runs the suite across every supported Ruby via mise; `rake ci`
+  adds RuboCop. CI uses `bundler-cache: true`.
+- **Releases publish from CI via Trusted Publishing.** Pushing a `v*` tag runs
+  the full gate and then exchanges GitHub's OIDC token for a short-lived,
+  push-scoped RubyGems credential — no API key is stored anywhere. Two gates run
+  first, both aimed at how 0.1.1 went out: the tag must match `Conexa::VERSION`
+  (the `v0.1.1` tag points at code carrying `0.1.0`), and the packaged gem must
+  contain only `lib/` and the documentation.
+
+### Removed
+- **Breaking**: `Conexa::Client`, `Conexa::Authenticator` and
+  `Conexa::TokenManager`. They referenced five `Conexa` module methods that never
+  existed (`credentials`, `secret_key`, `access_key`, `client_id`,
+  `default_client_key`), so any real use raised `NoMethodError`; their specs
+  passed only because they stubbed those methods into being. The `jwt` dependency
+  goes with them — `Conexa::Auth` (the v2 `/auth` resource) is unaffected.
+- **Breaking**: `Conexa::OrderCommon`. Unlike the three above, this one *ran* —
+  it built `/order/:id` and `/order/:id/refund` and issued a real `DELETE`. It is
+  removed because **API v2 documents no `/order` endpoint at all**: nothing in
+  the gem used it, no spec covered it, and it targets a surface that no longer
+  exists. Note that its documented backwards-compatible alias never worked:
+  `OrderCommom = self` inside the class body defines
+  `Conexa::OrderCommon::OrderCommom`, not `Conexa::OrderCommom`, so the pre-0.1.0
+  name has raised `NameError` since the rename.
+
+### Testing
+- VCR cassettes recorded against a real tenant are anonymised, and
+  `spec_helper.rb` filters the API token out of new recordings. The
+  `claude_scripts/sanitize_cassettes/` script does the anonymisation in place,
+  keeping the JSON shape so the specs still exercise the same structure.
+
 ## [0.1.1] - 2026-03-31
 
 ### Added
@@ -133,7 +338,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Charge with settle and PIX methods
 - Pagination support
 
-[Unreleased]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.0.9...v0.1.0
 [0.0.9]: https://github.com/guilhermegazzinelli/conexa-ruby/compare/v0.0.8...v0.0.9

data/README.md

@@ -25,8 +25,8 @@ gem install conexa
 
 ```ruby
 Conexa.configure do |config|
-  config.subdomain = 'YOUR_SUBDOMAIN'  # your-company.conexa.app
-  config.api_token = 'YOUR_API_TOKEN'  # Application Token from Conexa
+  config.api_host  = 'https://your-company.conexa.app'  # your tenant
+  config.api_token = 'YOUR_API_TOKEN'                   # Application Token from Conexa
 end
 ```
 
@@ -35,13 +35,45 @@ end
 1. **Application Token** (recommended): Created in Conexa at **Config > Integrações > API / Token**
 2. **Username/Password**: Use the `/auth` endpoint to get a JWT token
 
+### Read-only mode
+
+This gem talks to a billing system: settling a charge moves money and can issue
+an NF-e. When you only mean to read — auditing, reporting, investigating — turn
+writing off and let the gem refuse instead of trusting yourself to be careful.
+
+```ruby
+Conexa.configure { |config| config.read_only = true }
+
+Conexa::Charge.all(status: 'pending')   # fine
+Conexa::Charge.settle(789)              # raises Conexa::ReadOnlyError
+```
+
+Set `CONEXA_READ_ONLY=1` in the environment to default it on — useful in CI, or
+in any shell where you would rather not discover you were pointed at production.
+
+For a single block, without reconfiguring the client:
+
+```ruby
+Conexa.read_only do
+  report = Conexa::Charge.all(limit: 100)   # anything here is read-only
+end
+```
+
+The guard runs before the request leaves the process, so a blocked call never
+reaches your tenant. `GET` is allowed, and so is `POST /auth` — without it
+read-only mode could not obtain a token.
+
+**The block form is fiber-local.** It does not reach a `Thread` or `Fiber`
+spawned inside it, nor external iteration on an `Enumerator`. For anything
+concurrent use `config.read_only` (or `CONEXA_READ_ONLY`), which is global.
+
 ## Quick Start
 
 ```ruby
 require 'conexa'
 
 Conexa.configure do |config|
-  config.subdomain = 'mycompany'
+  config.api_host  = 'https://mycompany.conexa.app'
   config.api_token = ENV['CONEXA_API_TOKEN']
 end
 

data/README_pt-BR.md

@@ -37,7 +37,41 @@ Conexa.configure do |config|
 end
 ```
 
-Certifique-se de que as variáveis de ambiente `API_TOKEN` e `API_HOST` estejam configuradas com seu token e URL da API Conexa.
+Certifique-se de que as variáveis de ambiente `API_TOKEN` e `API_HOST` estejam configuradas com seu token e URL da API Conexa. O `api_host` é o subdomínio do seu tenant, por exemplo `https://minhaempresa.conexa.app`.
+
+### Modo somente-leitura
+
+Esta gem conversa com um sistema de cobrança: quitar uma cobrança movimenta
+dinheiro e pode emitir NF-e. Quando a intenção é apenas consultar — auditoria,
+relatório, investigação — desligue a escrita e deixe a gem recusar, em vez de
+confiar na própria atenção.
+
+```ruby
+Conexa.configure { |config| config.read_only = true }
+
+Conexa::Charge.all(status: 'pending')   # ok
+Conexa::Charge.settle(789)              # levanta Conexa::ReadOnlyError
+```
+
+Defina `CONEXA_READ_ONLY=1` no ambiente para ligar por padrão — útil em CI, ou em
+qualquer shell onde você prefira não descobrir que estava apontando para
+produção.
+
+Para um trecho específico, sem reconfigurar o cliente:
+
+```ruby
+Conexa.read_only do
+  relatorio = Conexa::Charge.all(limit: 100)   # tudo aqui dentro é leitura
+end
+```
+
+A verificação acontece antes de a requisição sair do processo, então uma chamada
+bloqueada nunca chega ao seu tenant. `GET` é permitido, e o `POST /auth` também —
+sem ele o modo leitura não conseguiria obter token.
+
+**O bloco é fiber-local.** Ele não alcança uma `Thread` ou `Fiber` criada lá
+dentro, nem iteração externa de `Enumerator`. Para qualquer coisa concorrente use
+`config.read_only` (ou `CONEXA_READ_ONLY`), que é global.
 
 ## Uso
 

data/REFERENCE.md

@@ -42,8 +42,9 @@ gem install conexa
 
 ```ruby
 Conexa.configure do |config|
-  config.api_host = 'https://api.conexa.com.br'  # or sandbox URL
+  config.api_host  = 'https://mycompany.conexa.app'  # your tenant subdomain
   config.api_token = 'your_api_token_here'
+  config.read_only = false                           # see below
 end
 
 # Rails: use generator
@@ -51,6 +52,33 @@ rails generate conexa:install
 # Creates config/initializers/conexa.rb
 ```
 
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `api_host` | `''` | Tenant base URL. `/index.php/api/v2` is appended automatically. |
+| `api_token` | `''` | Application Token — Config > Integrações > API / Token. |
+| `read_only` | `ENV['CONEXA_READ_ONLY']` | Refuse every non-GET request. |
+
+### Read-only mode
+
+Any request other than `GET` raises `Conexa::ReadOnlyError` before it leaves the
+process. `POST /auth` stays allowed — matched on the path, not on a caller flag —
+since read-only mode would otherwise be unable to obtain a token.
+
+`Conexa.read_only { }` is fiber-local: it does not reach a `Thread` or `Fiber`
+spawned inside the block. Use `config.read_only` for concurrent work.
+
+`CONEXA_READ_ONLY` is read at each check, so it applies even when set after
+`Conexa.configure`. Recognised: `1/true/yes/on` and `0/false/no/off`; anything
+else warns and is treated as off.
+
+```ruby
+Conexa.configure { |c| c.read_only = true }   # or CONEXA_READ_ONLY=1
+
+Conexa.read_only do                            # block-scoped, thread-local
+  Conexa::Charge.all(status: 'pending')
+end
+```
+
 ## Convention: snake_case
 
 This gem follows Ruby/Rails conventions. Use **snake_case** for all parameters - the gem automatically converts to camelCase for the API.

data/lib/conexa/configuration.rb

@@ -2,11 +2,57 @@
 
 module Conexa
   class Configuration
-    attr_accessor :api_token, :api_host
+    # @return [String] the Application Token, created in Conexa under
+    #   Config > Integrações > API / Token
+    attr_accessor :api_token
+
+    # @return [String] the tenant base URL, e.g. "https://mycompany.conexa.app"
+    attr_accessor :api_host
+
+    # Set to force read-only mode on or off, overriding the environment.
+    # @return [Boolean]
+    attr_writer :read_only
+
+    # Values that turn read-only mode on via CONEXA_READ_ONLY.
+    TRUTHY = %w[1 true yes on].freeze
+
+    # Values that explicitly turn it off. Anything else is a typo worth warning
+    # about — silently failing open on `CONEXA_READ_ONLY=treu` would leave an
+    # operator believing writes were blocked when they are not.
+    FALSEY = %w[0 false no off].freeze
 
     def initialize
       @api_token = ''
       @api_host = ''
+      @read_only = nil
+    end
+
+    # When true, any request other than GET raises {Conexa::ReadOnlyError} before
+    # reaching the network.
+    #
+    # Read lazily so that CONEXA_READ_ONLY still applies when it is set after
+    # {Conexa.configure} has run — it used to be captured once at initialization,
+    # which made setting it later a silent no-op. An explicit assignment always
+    # wins over the environment.
+    #
+    # @return [Boolean]
+    def read_only
+      return @read_only unless @read_only.nil?
+
+      env_read_only
+    end
+
+    private
+
+    def env_read_only
+      value = ENV["CONEXA_READ_ONLY"].to_s.strip.downcase
+      return false if value.empty?
+      return true  if TRUTHY.include?(value)
+      return false if FALSEY.include?(value)
+
+      warn "Conexa: CONEXA_READ_ONLY=#{value.inspect} não é reconhecido e foi ignorado " \
+           "(modo somente-leitura DESLIGADO). Use um de: #{(TRUTHY + FALSEY).join(", ")}."
+      false
     end
   end
-end
+end

data/lib/conexa/errors.rb

@@ -16,40 +16,112 @@ module Conexa
   class RequestError < ConexaError
   end
 
+  # Raised instead of performing a mutating request while Conexa.read_only?.
+  # The request never reaches the network.
+  class ReadOnlyError < ConexaError
+  end
+
   class ResponseError < ConexaError
     attr_reader :request_params, :error
 
-    def initialize(request_params, error, message=nil)
+    # The decoded error body, when the API returned one.
+    # @return [Hash]
+    attr_reader :api_response
+
+    def initialize(request_params, error, message=nil, api_response=nil)
       @request_params, @error = request_params, error
-      msg = @error.message
+      @api_response = api_response.is_a?(Hash) ? api_response : {}
+      msg = describe_error(error)
       msg +=  " => " + message if message
       super msg
     end
+
+    # The API's errors, normalised across its two shapes.
+    #
+    # Field validation answers `{"field": …, "messages": [...]}`; business rules
+    # answer `{"code": …, "message": …}`. Consumers that only handled the first
+    # rendered business-rule errors as blank strings — which is how
+    # CONTRACT_RECURRING_SALE_10 stayed invisible through eight attempts.
+    #
+    # @return [Array<Hash{Symbol=>String,nil}>] entries of {field:, code:, message:}
+    def api_errors
+      Array(api_response["errors"]).filter_map do |entry|
+        next unless entry.is_a?(Hash)
+
+        { field:   entry["field"],
+          code:    entry["code"],
+          message: entry["message"] || Array(entry["messages"]).join("; ") }
+      end
+    end
+
+    # Documented business-rule codes, e.g. "CHARGE_11" or
+    # "CONTRACT_RECURRING_SALE_10". These are what a caller branches on — for
+    # instance to tell an already-settled charge from a real settlement failure.
+    #
+    # @return [Array<String>]
+    def api_error_codes
+      api_errors.filter_map { |entry| entry[:code] }
+    end
+
+    # One readable line per error, whichever shape it arrived in.
+    # @return [Array<String>]
+    def api_error_messages
+      api_errors.map do |entry|
+        label = entry[:field] || entry[:code]
+        label ? "#{label}: #{entry[:message]}" : entry[:message]
+      end
+    end
+
+    private
+
+    # `error` is usually a RestClient::Exception, but the malformed-body path
+    # hands us a RestClient::Response, which has no #message — that used to raise
+    # NoMethodError from inside the error constructor itself.
+    def describe_error(error)
+      return error.message if error.respond_to?(:message) && error.message
+      return "HTTP #{error.code}: #{error.body.to_s[0, 200]}" if error.respond_to?(:code)
+
+      error.to_s
+    end
   end
 
   class NotFound < ResponseError
     attr_reader :response
     def initialize(response, request_params, error)
       @response = response
-      super request_params, error, response&.dig('message')
+      super request_params, error, response&.dig('message'), response
     end
   end
 
+  # Raised for an error body with no `message` key.
+  #
+  # Every error response the published collection documents carries a `message`,
+  # so in practice this is reached only by an undocumented or malformed body. It
+  # used to render as the bare string "Conexa::ValidationError" and `#to_h` raised
+  # NoMethodError; both now degrade to something a caller can act on.
   class ValidationError < ConexaError
     attr_reader :response, :errors
 
     def initialize(response)
       @response = response
-      @errors   = response['message']&.map do |msg|
-        params = msg.values_at('message', 'parameter_name', 'type', 'url')
-        ParamError.new(*params)
+      @errors   = Array(response.is_a?(Hash) ? response['message'] : nil).filter_map do |msg|
+        next unless msg.is_a?(Hash)
+
+        ParamError.new(*msg.values_at('message', 'parameter_name', 'type', 'url'))
       end
-      super @errors&.map(&:message)&.join(', ')
+
+      super(@errors.any? ? @errors.map(&:message).join(', ') : describe(response))
     end
 
     def to_h
       @errors.map(&:to_h)
     end
+
+    private
+
+    def describe(response)
+      "The API returned an error with no message: #{response.inspect[0, 200]}"
+    end
   end
 
   class MissingCredentialsError < ConexaError