resteze 0.4.0 → 1.0.0

data/docs/API.md

@@ -163,34 +163,23 @@ user.refresh  # Re-fetches from API
 
 ### Custom Request Methods
 
+Declare extra endpoints with the `action` DSL. See [ACTIONS.md](ACTIONS.md) for
+the full option table, re-routing the built-ins, and API-wide defaults.
+
 ```ruby
 module MyApi
   class User < ApiResource
     property :id
     property :email
     property :status
-    
-    # Instance method for custom action
-    def activate!
-      response = request(
-        :post,
-        "#{resource_path}/activate",
-        params: { send_email: true }
-      )
-      initialize_from(response.data)
-    end
-    
-    # Class method for custom endpoint
-    def self.search(query)
-      response = request(
-        :get,
-        "#{resource_path}/search",
-        params: { q: query }
-      )
-      response.data.map { |attrs| construct_from(attrs) }
-    end
-    
-    # Custom headers
+
+    # Member action: user.activate(send_email: true) => POST /users/:id/activate
+    action :activate, method: :post, on: :member, returns: :self
+
+    # Collection action: User.search(q: "jane") => GET /users/search?q=jane
+    action :search, method: :get, returns: :self
+
+    # Anything the DSL does not express is still one request call away
     def update_with_version(version, attributes)
       request(
         :patch,
@@ -228,12 +217,17 @@ response = MyApi::User.request(:get, '/users')
 
 # Access response data
 response.data          # Parsed response body
-response.status        # HTTP status code
-response.headers       # Response headers
-response.body          # Raw response body
+response.http_status   # HTTP status code
+response.http_headers  # Response headers
+response.http_body     # Raw response body
 response.request_id    # Request ID from headers (if present)
+response.success?      # true for any 2xx status
+response.ok?           # true only for 200
+response.rate_limit    # MyApi.rate_limiter.rate_limit(response): the strategy's view, or nil
 ```
 
+For APIs that report failures inside a successful response, override `MyApi::Response.body_error` to return an error to raise; see [Errors Reported in a 2xx Body](ERROR_HANDLING.md#errors-reported-in-a-2xx-body).
+
 ### Working with Objects
 
 ```ruby

data/docs/CONFIGURATION.md

@@ -2,11 +2,13 @@
 
 ## Table of Contents
 - [Basic Configuration](#basic-configuration)
+- [Authentication](#authentication)
 - [Environment-based Configuration](#environment-based-configuration)
 - [Dynamic Configuration](#dynamic-configuration)
 - [Connection Configuration](#connection-configuration)
 - [Logging Configuration](#logging-configuration)
 - [Proxy Configuration](#proxy-configuration)
+- [Rate Limits](#rate-limits)
 - [Advanced Configuration Patterns](#advanced-configuration-patterns)
 
 ## Basic Configuration
@@ -81,6 +83,90 @@ module MyApi
 end
 ```
 
+## Authentication
+
+Each module gets a `MyApi::Authenticator`, a subclass of `Resteze::Authenticator` that does nothing until you choose a scheme with `authenticate_with` on the module. A scheme is a `Resteze::Authenticator::Strategy` subclass; it expects its credential in a conventional module setting, declares that setting on the module when chosen, and reads it on every request, so an initializer fills it through `configure` like any other setting and a rotated value takes effect without a restart. A setting that is still `nil` when a request goes out raises an `ArgumentError` naming it rather than sending an empty credential; `MyApi.authenticator.missing_settings` lists them for a boot-time check.
+
+```ruby
+module MyApi
+  include Resteze
+
+  authenticate_with :api_key, header: 'X-Api-Key'   # expects MyApi.api_key
+end
+
+# config/initializers/my_api.rb
+MyApi.configure do |config|
+  config.api_key = ENV['MY_API_KEY']
+end
+```
+
+The convention is a default. Any credential option also takes a Symbol naming a different setting (`value: :partner_key`), a callable (`value: -> { TokenStore.current }`), or a literal. Schemes combine; call `authenticate_with` once per scheme. (`strategy` inside `class Authenticator` is the same thing, for when you are reopening the class anyway to override its lifecycle.)
+
+### Built-in schemes
+
+| Scheme | Expects | Options | Sends |
+|---|---|---|---|
+| `:api_key` | `api_key` | `value:`, and `header:` (default `X-Api-Key`) or `query:` | the key in that header, or in the query string on every request whatever the method |
+| `:basic` | `username`, `password` | `username:`, `password:` | `Authorization: Basic …` |
+| `:bearer` | `api_key` | `token:`, `scheme:` (default `Bearer`) | `Authorization: Bearer …`; `scheme: 'Token'` for another prefix |
+| `:mtls` | `client_cert`, `client_key`; optionally `client_key_passphrase`, `ca_file` | `cert:`, `key:`, `passphrase:`, `ca_file:`, `verify:` | a client certificate on the TLS connection; nothing on the requests |
+
+`cert:` and `key:` for `:mtls` are PEM strings or paths to PEM files, from the settings, a callable, or a literal. A path is read as given when the connection is first built, so make it absolute (`Rails.root.join(...)`); a relative path resolves against whatever the process's working directory happens to be at that moment. The certificate is applied when `Client.default_connection` builds the connection, so an override of that method must pass `connection_options` to Faraday itself. `missing_settings` leaves a scheme's optional settings alone, so an unencrypted key with no passphrase is not reported as missing. `verify: false` logs a warning through the module's logger every time a connection is built with it.
+
+### The lifecycle
+
+The client calls the authenticator at three points: `connection_options` when the per-thread connection is built (an override of `Client.default_connection` must pass them to Faraday itself), `apply(request)` before every request (with `headers`, `params` and `query` to mutate; `query` always goes in the query string whatever the method), and `refresh?(error, attempt)` after a `MyApi::AuthenticationError`, where returning `true` sends the request once more with a renewed credential.
+
+### Credentials and the log
+
+At `Logger::DEBUG` the client logs the whole request, headers and query string included. Each strategy names where it put the credential through `sensitive_keys` (`{ headers: [...], query: [...], params: [...] }`), and the client replaces those values with `[REDACTED]` in the logged copy only; the request goes out intact. The built-ins all declare theirs. `Authorization` and `Proxy-Authorization` are masked whatever the strategies say, which also covers a credential added through an overridden `request_headers`.
+
+### Writing a scheme
+
+Subclass `Resteze::Authenticator::Strategy` and implement `apply(request, state)`; add `connection_options` or `refresh?(error, attempt, state)` when needed. A `DEFAULTS` constant whose Symbol values name module settings makes `authenticate_with` declare those settings; list in `OPTIONAL` any the scheme works without, and `missing_settings` will not report them. `resolve` reads an option whether it is a Symbol (from the module), a callable, or a literal; `resolve!` does the same and raises a clear `ArgumentError` on `nil`; `required!(name, value)` in a constructor rejects `nil` for an option that must be given. Implement `sensitive_keys` to name the header, query or body keys the credential lands under, or it will appear in the `DEBUG` log. `state` is a hash shared by every thread and every strategy on the authenticator, already under its lock, so a cached credential needs no synchronisation of its own; prefix your keys with the scheme's name. Options after the class go to your constructor.
+
+```ruby
+module MyApi
+  class SessionToken < Resteze::Authenticator::Strategy
+    DEFAULTS = { username: :username, password: :password }.freeze   # the settings this scheme expects
+
+    def initialize(login_url:, username: :username, password: :password)
+      super()
+      @login_url, @username, @password = login_url, username, password
+    end
+
+    def apply(request, state)
+      state[:session_token] ||= login
+      request.headers['X-Session-Token'] = state[:session_token]
+    end
+
+    def refresh?(_error, attempt, state)
+      return false if attempt > 1
+
+      state[:session_token] = login
+      true
+    end
+
+    def sensitive_keys
+      { headers: ['X-Session-Token'] }   # masked in the DEBUG log
+    end
+
+    private
+
+    def login
+      body = { username: resolve!(:username, @username), password: resolve!(:password, @password) }.to_json
+      JSON.parse(Faraday.post(@login_url, body, 'Content-Type' => 'application/json').body).fetch('token')
+    end
+  end
+
+  authenticate_with SessionToken, login_url: 'https://api.example.com/login'   # expects MyApi.username and .password
+end
+```
+
+`Resteze::Authenticator::Strategy.register(:session_token, SessionToken)` gives a scheme a name, so `authenticate_with :session_token` works like a built-in; a gem that ships a scheme registers it this way.
+
+`MyApi.authenticator` is the instance the client uses; assign another to replace it (tests do this to swap credentials) or `nil` to restore the default. `Client#request_headers` remains overridable for headers that are not a credential.
+
 ## Environment-based Configuration
 
 ### Using Rails Environments
@@ -535,6 +621,201 @@ module MyApi
 end
 ```
 
+## Rate Limits
+
+### The RateLimiter
+
+APIs disagree about rate limits: which headers carry the quota, whether the reset is an epoch or a countdown, whether a 429 is the only signal, whether the client should pace itself or just react. Resteze assumes none of it. `include Resteze` gives your module a `MyApi::RateLimiter`, a subclass of `Resteze::RateLimiter` whose every method is a no-op, and the client calls one instance of it, shared by every thread, at fixed points in each request:
+
+| Called | When | Default |
+|---|---|---|
+| `before_request(method, path, params:, headers:)` | before sending | waits for the strategy, if one is configured |
+| `track(response_or_error)` | after every `Response` and every `MyApi::Error` | lets the strategy learn from the API |
+| `retry?(error, attempt)` | after a `MyApi::RateLimitError`; `attempt` starts at 1 | `false` |
+| `retry_after(error)` | before a retry | the error's `Retry-After` |
+| `rate_limit(response_or_error)` | when `rate_limit` is read on a response or error | the strategy's view, else `nil` |
+
+The instance is `MyApi.rate_limiter`; assign one to replace it. Each attempt of a retried request is logged and instrumented on its own.
+
+### Choosing a strategy
+
+The four common algorithms are built in. Pick one with `strategy` in your module's `RateLimiter`:
+
+```ruby
+module Braze
+  class RateLimiter
+    strategy :fixed_window, limit: 250_000, window: 3600, headers: true
+  end
+end
+```
+
+| Strategy | Options | Behaviour |
+|---|---|---|
+| `:fixed_window` | `limit:`, `window:` seconds, `headers:`, `reset:` | At most `limit` requests per window, windows aligned to the first request. With `headers: true` the budget and window follow the API's `X-RateLimit-Limit`, `-Remaining` and `-Reset` headers, which is how Braze and JD Power report theirs; pass a Hash to name other headers, and `reset: :seconds` when the reset header is a countdown rather than a time. `limit:` may be omitted when the API sends it, or sends only the remaining count. Syncing is conservative: within a window the lower of the local and reported remaining counts wins, since requests admitted after the server answered are not in its number yet; a reset beyond the local window starts a fresh one; non-finite or far-future resets are not trusted |
+| `:sliding_window` | `limit:`, `window:` seconds | At most `limit` requests in any trailing window. Exact; memory bounded by `limit` |
+| `:token_bucket` | `capacity:`, `refill_rate:` per second | Bursts up to `capacity`, then paced at the refill rate |
+| `:leaky_bucket` | `capacity:`, `leak_rate:` per second | Smooths bursts into a steady rate; a full bucket waits for room |
+
+With a strategy, `before_request` waits until the request fits, outside the lock so one thread's wait never blocks another's bookkeeping, and `rate_limit` on any response or error returns a `Resteze::RateLimit` (`limit`, `remaining`, `reset`, `exhausted?`) of the strategy's current view. For your own algorithm, subclass `Resteze::RateLimiter::Strategy` and pass the class to `strategy`; options after it go to your constructor. `acquire(state, now)` is required: record one request in `state` and return `0`, or record nothing and return the seconds until one could be admitted. `observe(state, response, now)` and `describe(state, now)` are optional. `state` is the limiter's hash, already under its lock, and the strategy itself must stay stateless. A daily quota aligned to midnight UTC:
+
+```ruby
+module MyApi
+  class DailyQuota < Resteze::RateLimiter::Strategy
+    DAY = 86_400
+
+    def initialize(limit:)
+      super()
+      @limit = limit
+    end
+
+    def acquire(state, now)
+      roll(state, now)
+      return (state[:day_started] + DAY) - now if state[:count] >= @limit
+
+      state[:count] += 1
+      0
+    end
+
+    def observe(state, response, now)
+      data = response.respond_to?(:data) ? response.data : response.json_body
+      return unless data.is_a?(Hash) && data[:calls_remaining]
+
+      roll(state, now)
+      state[:count] = @limit - data[:calls_remaining].to_i
+    end
+
+    def describe(state, now)
+      roll(state, now)
+      Resteze::RateLimit.new(limit: @limit, remaining: @limit - state[:count], reset: state[:day_started] + DAY)
+    end
+
+    private
+
+    def roll(state, now)
+      today = now - (now % DAY)
+      return if state[:day_started] == today
+
+      state[:day_started] = today
+      state[:count]       = 0
+    end
+  end
+
+  class RateLimiter
+    strategy DailyQuota, limit: 10_000
+  end
+end
+```
+
+### Reacting to a 429
+
+A strategy keeps you under the limit; `retry?` and `retry_after` say what to do when the API disagrees. Override them alongside, or instead of, a strategy:
+
+```ruby
+module Braze
+  class RateLimiter
+    strategy :fixed_window, limit: 250_000, window: 3600, headers: true
+
+    def retry?(_error, attempt)
+      attempt <= 3
+    end
+  end
+end
+```
+
+`retry_after` reads the HTTP `Retry-After` header, accepting delay-seconds or an HTTP-date. For an API that signals the wait another way, override it; `header` does a case-insensitive lookup on the error:
+
+```ruby
+def retry_after(error)
+  error.header('X-Retry-In')&.to_i || super
+end
+```
+
+### Waiting without blocking
+
+With a strategy, `before_request` waits in the calling thread by default (`on_wait: :sleep`). A background job would often rather give the thread back and reschedule itself. `on_wait: :raise` makes the limiter raise `MyApi::RateLimitError` instead of waiting, with the computed wait in `retry_after` and no `http_status`, since nothing was sent. An error raised this way never goes through `retry?`; it is a refusal, not a failed attempt.
+
+```ruby
+module Braze
+  class RateLimiter
+    strategy :fixed_window, limit: 250_000, window: 3600, headers: true, on_wait: :raise
+  end
+end
+
+class TrackEventsJob
+  include Sidekiq::Job
+
+  sidekiq_retry_in do |_count, exception|
+    exception.respond_to?(:retry_after) ? (exception.retry_after || 60) : :default
+  end
+
+  def perform(events)
+    Braze::User.track(events:)   # a spent budget, or a 429, raises; Sidekiq reschedules
+  end
+end
+```
+
+The same option is accepted by the constructor, `MyApi::RateLimiter.new(on_wait: :raise)`, and `RateLimitError.new(message, retry_after: seconds)` builds such an error by hand. Under `on_wait: :raise` a retry decided by `retry?` is not slept either: the 429 itself is raised, with its `retry_after`, so both cases reach the job the same way.
+
+Every wait, whether from a strategy or before a retry, is clamped to `max_wait` seconds, one hour by default. A `Retry-After` or reset header that is absurd, non-finite or malicious therefore costs at most one `max_wait`, never a thread parked for a year or a crash on `sleep(Infinity)`. Set it alongside `on_wait:` in `strategy`, or in the constructor:
+
+```ruby
+strategy :fixed_window, limit: 1000, window: 60, max_wait: 120
+```
+
+### Overriding the lifecycle
+
+Any method can be overridden; call `super` to keep the strategy's behaviour. State belongs in the limiter's mutex-guarded hash, never in instance variables, so a subclass stays thread-safe without doing anything: `state` returns a snapshot, `update_state` merges values, and `synchronize { |state| ... }` yields the live hash for read-modify-write sequences.
+
+```ruby
+module Braze
+  class RateLimiter
+    strategy :fixed_window, limit: 250_000, window: 3600, headers: true
+
+    def before_request(method, path, **)
+      raise RateLimitError, "budget reserved for exports" if path.start_with?("/users/export") && state[:remaining].to_i < 1000
+
+      super
+    end
+
+    def track(response)
+      super
+      update_state(remaining: response.rate_limit&.remaining)
+    end
+  end
+end
+```
+
+`Resteze::RateLimit.from_headers(headers, names = {})` remains available as a helper for reading the three-header shape by hand.
+
+### Retrying after a 429
+
+Resteze retries a 429 only when your `RateLimiter`'s `retry?` says so. For retries handled below the limiter, with backoff and per-status rules, add the [`faraday-retry`](https://github.com/lostisland/faraday-retry) gem (it is not a Resteze dependency) and place it **after** `RaiseError` in the stack. That puts it closer to the adapter, so it sees the raw 429 and retries before `RaiseError` turns the final answer into an error. `retry_statuses: [429]` makes it honor `Retry-After` automatically.
+
+```ruby
+require 'faraday/retry'
+
+module MyApi
+  class Client < Resteze::Client
+    def self.default_connection
+      Thread.current["#{client_name}_default_connection"] ||= Faraday.new do |conn|
+        conn.use Faraday::Request::UrlEncoded
+        conn.use Middleware::RaiseError
+        conn.request :retry,
+                     max: 3,
+                     interval: 0.5,
+                     backoff_factor: 2,
+                     retry_statuses: [429],
+                     methods: %i[get post]   # POST is not retried by default; add it only
+                                             # where the API treats a 429 as "not processed"
+        conn.adapter Faraday.default_adapter
+      end
+    end
+  end
+end
+```
+
+For an API that signals the wait through a non-standard header, pass `rate_limit_retry_header:` and `rate_limit_reset_header:`, with a `header_parser_block:` to convert the value into seconds. See the faraday-retry README.
+
 ## Advanced Configuration Patterns
 
 ### Configuration with Validation

data/docs/ERROR_HANDLING.md

@@ -5,32 +5,38 @@
 - [Built-in Error Types](#built-in-error-types)
 - [Error Attributes](#error-attributes)
 - [Handling Errors](#handling-errors)
+- [Errors Reported in a 2xx Body](#errors-reported-in-a-2xx-body)
 - [Custom Error Classes](#custom-error-classes)
 - [Middleware Error Handling](#middleware-error-handling)
 - [Best Practices](#best-practices)
 
 ## Error Hierarchy
 
-Resteze provides a comprehensive error hierarchy that gets dynamically created for each API module:
+Resteze creates a full error hierarchy inside each API module. Every class below is a subclass of that module's own `Error`, so `rescue YourApi::Error` catches everything the client raises, and an error from one API is never caught by a rescue clause written for another.
 
 ```
 StandardError
-└── YourApi::Error (base for all API errors)
-    ├── YourApi::ApiError (server-side errors)
-    ├── YourApi::ApiConnectionError (network/connection errors)
-    └── YourApi::InvalidRequestError (client-side errors)
-
-Additional wrapped errors:
-├── YourApi::NotImplementedError
-├── YourApi::ResourceNotFound (404)
-├── YourApi::UnprocessableEntityError (422)
-└── YourApi::ConflictError (409)
+└── Resteze::Error
+    └── YourApi::Error (base for all of this API's errors)
+        ├── YourApi::ApiError            (5xx, and 4xx with no more specific class)
+        ├── YourApi::ApiConnectionError  (connection refused, timeout, SSL)
+        ├── YourApi::AuthenticationError (401, 403)
+        ├── YourApi::InvalidRequestError (400, and requests the client cannot build)
+        ├── YourApi::RateLimitError      (429, with #retry_after)
+        ├── YourApi::ResourceNotFound    (404)
+        ├── YourApi::ConflictError       (409)
+        └── YourApi::UnprocessableEntityError (422)
+
+Also namespaced:
+└── YourApi::NotImplementedError
 ```
 
+The `RaiseError` middleware maps every Faraday error onto this hierarchy. The original Faraday error is available as `e.cause`.
+
 ## Built-in Error Types
 
 ### ApiError
-Server-side errors (5xx status codes):
+Server-side errors (5xx), plus any 4xx that has no more specific class (for example 405 or 410):
 
 ```ruby
 begin
@@ -38,7 +44,8 @@ begin
 rescue MyApi::ApiError => e
   puts "Server error: #{e.message}"
   puts "HTTP Status: #{e.http_status}"
-  puts "Response body: #{e.response.body}"
+  puts "Response body: #{e.http_body}"
+  puts "Parsed body: #{e.json_body.inspect}"   # nil unless the body parsed as JSON or XML
   
   # Retry logic for server errors
   retry if e.http_status >= 500
@@ -67,7 +74,7 @@ end
 ```
 
 ### InvalidRequestError
-Client-side errors (4xx status codes):
+A `400 Bad Request`, or a request the client could not build (for example `refresh` on an object with no id):
 
 ```ruby
 begin
@@ -75,13 +82,37 @@ begin
 rescue MyApi::InvalidRequestError => e
   puts "Invalid request: #{e.message}"
   puts "Invalid parameter: #{e.param}" if e.param
-  puts "HTTP Status: #{e.http_status}"
+  puts "HTTP Status: #{e.http_status}"   # nil when the request was never sent
   
   # Don't retry - fix the request
   log_validation_error(e)
 end
 ```
 
+### AuthenticationError
+`401 Unauthorized` and `403 Forbidden`:
+
+```ruby
+begin
+  user = MyApi::User.retrieve('123')
+rescue MyApi::AuthenticationError => e
+  puts "Check the API key: #{e.message}"
+end
+```
+
+### RateLimitError
+`429 Too Many Requests`. `retry_after` reads the `Retry-After` header as seconds, accepting either delay-seconds or an HTTP-date, and is `nil` when the header is absent. `rate_limit` exposes your module's `RateLimiter` view of the limit, and that limiter decides whether the client retries (see [Rate Limits](CONFIGURATION.md#rate-limits)):
+
+```ruby
+begin
+  MyApi::Event.track(events: batch)
+rescue MyApi::RateLimitError => e
+  e.rate_limit&.remaining   # 0
+  sleep(e.retry_after || 1)
+  retry
+end
+```
+
 ### ResourceNotFound
 404 Not Found errors:
 
@@ -105,7 +136,7 @@ rescue MyApi::UnprocessableEntityError => e
   puts "Validation failed: #{e.message}"
   
   # Parse validation errors from response
-  errors = JSON.parse(e.response.body)['errors']
+  errors = JSON.parse(e.response[:body])['errors']
   errors.each do |field, messages|
     puts "#{field}: #{messages.join(', ')}"
   end
@@ -127,27 +158,32 @@ end
 
 ## Error Attributes
 
-All error classes include these attributes:
+Every subclass of `MyApi::Error` carries the HTTP response that produced it:
 
 ```ruby
 begin
   MyApi::User.retrieve('123')
 rescue MyApi::Error => e
-  # Basic attributes
   e.message       # Error message
-  e.http_status   # HTTP status code (e.g., 404, 500)
-  e.response      # Faraday response object
-  
-  # Response details
-  e.response.body    # Raw response body
-  e.response.headers # Response headers
-  e.response.status  # Status code
-  
+  e.http_status   # HTTP status code (e.g., 401, 500); nil for connection failures
+  e.http_body     # Raw response body
+  e.http_headers  # Response headers
+  e.header("Retry-After")  # Case-insensitive header lookup
+  e.json_body     # Body parsed as JSON or XML, or nil
+  e.response      # Faraday's response hash: { status:, headers:, body:, request: }
+  e.cause         # The original Faraday error
+  e.rate_limit    # MyApi.rate_limiter.rate_limit(e): the strategy's view, or nil
+
   # For InvalidRequestError
-  e.param         # The parameter that caused the error
+  e.param         # The parameter that caused the error, when known
+
+  # For RateLimitError
+  e.retry_after   # Seconds to wait, from Retry-After, or nil
 end
 ```
 
+Every error also answers Faraday's reader names, `response_status`, `response_headers` and `response_body`, as aliases of the `http_` readers. Code written against the earlier Faraday-derived `ResourceNotFound`, `UnprocessableEntityError` and `ConflictError` keeps working.
+
 ## Handling Errors
 
 ### Basic Error Handling
@@ -276,6 +312,37 @@ end
 user = RetryableRequest.execute { MyApi::User.retrieve('123') }
 ```
 
+## Errors Reported in a 2xx Body
+
+Some APIs answer with a successful HTTP status and put the failure in the body. Braze, for example, returns `201 Created` with `{"message": "success", "errors": [...]}` when some records in a batch were rejected, and `200 OK` with `{"message": "Invalid API key"}` for others. The status-based middleware cannot see these.
+
+Override `body_error` on your module's `Response`. It receives the parsed `Response` after the middleware has accepted the status. Return an exception to raise it, or `nil` to accept the response. `Error.from_response` builds a namespaced error that carries the status, headers, body and parsed `json_body`, with the `Response` itself as `e.response`:
+
+```ruby
+module MyApi
+  class Response
+    SUCCESS = %w[success queued].freeze
+
+    def self.body_error(response)
+      data = response.data
+      return unless data.is_a?(Hash)
+      return if SUCCESS.include?(data[:message]) && data[:errors].blank?
+
+      ApiError.from_response(response, data[:message] || "errors in response body")
+    end
+  end
+end
+
+begin
+  MyApi::User.track(events: batch)
+rescue MyApi::ApiError => e
+  e.http_status          # 201
+  e.json_body[:errors]   # the per-record errors
+end
+```
+
+The hook runs inside `execute_request`, so the error is instrumented with its status like any other, and `rescue MyApi::Error` catches it. Return a subclass of `ApiError` if callers need to tell partial success apart from a hard failure.
+
 ## Custom Error Classes
 
 ### Defining Custom Errors

data/docs/TESTING.md

@@ -161,6 +161,27 @@ class UserTest < ApiTestCase
 end
 ```
 
+### Testing Actions
+
+`has_action` (from `Resteze::Testing::Minitest::Object` or
+`Resteze::Testing::RSpec::Object`) asserts an action is declared and checks any
+options you pass. `path:` is the full routed path, with the id `"ID"` for member
+actions.
+
+```ruby
+class CampaignTest < Minitest::Spec
+  include Resteze::Testing::Minitest::Object
+
+  subject { TestApi::Campaign }
+
+  it "routes its actions" do
+    has_action :data_series, method: :get, on: :collection, path: "/campaigns/data_series"
+    has_action :duplicate, method: :post, on: :member, id: :param, path: "/campaigns/duplicate"
+    has_action :retrieve, path: "/campaigns/details"
+  end
+end
+```
+
 ### Testing Lists
 
 ```ruby