sec_api 1.0.0

data/lib/sec_api/metrics_collector.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+module SecApi
+  # Provides centralized metric recording for SEC API operations.
+  #
+  # This module standardizes metric names and tags across all integrations.
+  # Use directly with your metrics backend, or configure via `metrics_backend`
+  # for automatic metrics collection.
+  #
+  # All metric methods are safe to call - they will not raise exceptions even
+  # if the backend is nil, misconfigured, or raises errors. This ensures that
+  # metrics never break production operations.
+  #
+  # @example Direct usage with StatsD
+  #   statsd = Datadog::Statsd.new('localhost', 8125)
+  #
+  #   config.on_response = ->(request_id:, status:, duration_ms:, url:, method:) {
+  #     SecApi::MetricsCollector.record_response(statsd,
+  #       status: status,
+  #       duration_ms: duration_ms,
+  #       method: method
+  #     )
+  #   }
+  #
+  # @example Automatic metrics with metrics_backend
+  #   config = SecApi::Config.new(
+  #     api_key: "...",
+  #     metrics_backend: Datadog::Statsd.new('localhost', 8125)
+  #   )
+  #   # Metrics automatically collected for all operations
+  #
+  # @example New Relic custom events
+  #   config.on_response = ->(request_id:, status:, duration_ms:, url:, method:) {
+  #     NewRelic::Agent.record_custom_event("SecApiRequest", {
+  #       request_id: request_id,
+  #       status: status,
+  #       duration_ms: duration_ms,
+  #       method: method.to_s.upcase
+  #     })
+  #   }
+  #
+  # @example Datadog APM integration
+  #   config.on_request = ->(request_id:, method:, url:, headers:) {
+  #     Datadog::Tracing.trace('sec_api.request') do |span|
+  #       span.set_tag('request_id', request_id)
+  #       span.set_tag('http.method', method.to_s.upcase)
+  #       span.set_tag('http.url', url)
+  #     end
+  #   }
+  #
+  # @example OpenTelemetry spans
+  #   tracer = OpenTelemetry.tracer_provider.tracer('sec_api')
+  #
+  #   config.on_request = ->(request_id:, method:, url:, headers:) {
+  #     tracer.in_span('sec_api.request', attributes: {
+  #       'sec_api.request_id' => request_id,
+  #       'http.method' => method.to_s.upcase,
+  #       'http.url' => url
+  #     }) { }
+  #   }
+  #
+  # @example Prometheus push gateway
+  #   prometheus = Prometheus::Client.registry
+  #   requests_total = prometheus.counter(:sec_api_requests_total, labels: [:method, :status])
+  #   duration_histogram = prometheus.histogram(:sec_api_request_duration_seconds, labels: [:method])
+  #
+  #   config.on_response = ->(request_id:, status:, duration_ms:, url:, method:) {
+  #     requests_total.increment(labels: {method: method.to_s.upcase, status: status.to_s})
+  #     duration_histogram.observe(duration_ms / 1000.0, labels: {method: method.to_s.upcase})
+  #   }
+  #
+  module MetricsCollector
+    extend self
+
+    # Metric name for total requests made (counter).
+    # @return [String] metric name
+    REQUESTS_TOTAL = "sec_api.requests.total"
+
+    # Metric name for successful requests (counter, status < 400).
+    # @return [String] metric name
+    REQUESTS_SUCCESS = "sec_api.requests.success"
+
+    # Metric name for error requests (counter, status >= 400).
+    # @return [String] metric name
+    REQUESTS_ERROR = "sec_api.requests.error"
+
+    # Metric name for request duration (histogram, milliseconds).
+    # @return [String] metric name
+    REQUESTS_DURATION = "sec_api.requests.duration_ms"
+
+    # Metric name for retry attempts (counter).
+    # @return [String] metric name
+    RETRIES_TOTAL = "sec_api.retries.total"
+
+    # Metric name for exhausted retries (counter).
+    # @return [String] metric name
+    RETRIES_EXHAUSTED = "sec_api.retries.exhausted"
+
+    # Metric name for rate limit hits (counter, 429 responses).
+    # @return [String] metric name
+    RATE_LIMIT_HIT = "sec_api.rate_limit.hit"
+
+    # Metric name for proactive throttling events (counter).
+    # @return [String] metric name
+    RATE_LIMIT_THROTTLE = "sec_api.rate_limit.throttle"
+
+    # Metric name for streaming filings received (counter).
+    # @return [String] metric name
+    STREAM_FILINGS = "sec_api.stream.filings"
+
+    # Metric name for streaming delivery latency (histogram, milliseconds).
+    # @return [String] metric name
+    STREAM_LATENCY = "sec_api.stream.latency_ms"
+
+    # Metric name for stream reconnection events (counter).
+    # @return [String] metric name
+    STREAM_RECONNECTS = "sec_api.stream.reconnects"
+
+    # Metric name for filing journey stage duration (histogram, milliseconds).
+    # @return [String] metric name
+    JOURNEY_STAGE_DURATION = "sec_api.filing.journey.stage_ms"
+
+    # Metric name for total filing journey duration (histogram, milliseconds).
+    # @return [String] metric name
+    JOURNEY_TOTAL_DURATION = "sec_api.filing.journey.total_ms"
+
+    # Records a successful or failed response.
+    #
+    # Increments request counters and records duration histogram.
+    # Status codes < 400 are considered successful, >= 400 are errors.
+    #
+    # @param backend [Object] Metrics backend (StatsD, Datadog::Statsd, etc.)
+    # @param status [Integer] HTTP status code
+    # @param duration_ms [Integer] Request duration in milliseconds
+    # @param method [Symbol] HTTP method (:get, :post, etc.)
+    # @return [void]
+    #
+    # @example Record a successful response
+    #   MetricsCollector.record_response(statsd, status: 200, duration_ms: 150, method: :get)
+    #
+    # @example Record an error response
+    #   MetricsCollector.record_response(statsd, status: 429, duration_ms: 50, method: :get)
+    #
+    def record_response(backend, status:, duration_ms:, method:)
+      tags = {method: method.to_s.upcase, status: status.to_s}
+
+      increment(backend, REQUESTS_TOTAL, tags: tags)
+
+      if status < 400
+        increment(backend, REQUESTS_SUCCESS, tags: tags)
+      else
+        increment(backend, REQUESTS_ERROR, tags: tags)
+      end
+
+      histogram(backend, REQUESTS_DURATION, duration_ms, tags: tags)
+    end
+
+    # Records a retry attempt.
+    #
+    # @param backend [Object] Metrics backend
+    # @param attempt [Integer] Retry attempt number (1-indexed)
+    # @param error_class [String] Exception class name that triggered retry
+    # @return [void]
+    #
+    # @example Record a retry attempt
+    #   MetricsCollector.record_retry(statsd, attempt: 1, error_class: "SecApi::NetworkError")
+    #
+    def record_retry(backend, attempt:, error_class:)
+      tags = {attempt: attempt.to_s, error_class: error_class}
+      increment(backend, RETRIES_TOTAL, tags: tags)
+    end
+
+    # Records a final error (all retries exhausted).
+    #
+    # @param backend [Object] Metrics backend
+    # @param error_class [String] Exception class name
+    # @param method [Symbol] HTTP method
+    # @return [void]
+    #
+    # @example Record a final error
+    #   MetricsCollector.record_error(statsd, error_class: "SecApi::NetworkError", method: :get)
+    #
+    def record_error(backend, error_class:, method:)
+      tags = {error_class: error_class, method: method.to_s.upcase}
+      increment(backend, RETRIES_EXHAUSTED, tags: tags)
+    end
+
+    # Records a rate limit (429) response.
+    #
+    # @param backend [Object] Metrics backend
+    # @param retry_after [Integer, nil] Seconds to wait before retry
+    # @return [void]
+    #
+    # @example Record a rate limit hit
+    #   MetricsCollector.record_rate_limit(statsd, retry_after: 30)
+    #
+    def record_rate_limit(backend, retry_after: nil)
+      increment(backend, RATE_LIMIT_HIT)
+      gauge(backend, "sec_api.rate_limit.retry_after", retry_after) if retry_after
+    end
+
+    # Records proactive throttling.
+    #
+    # Called when the rate limiter proactively delays a request to avoid
+    # hitting the rate limit.
+    #
+    # @param backend [Object] Metrics backend
+    # @param remaining [Integer] Requests remaining before limit
+    # @param delay [Float] Seconds the request was delayed
+    # @return [void]
+    #
+    # @example Record proactive throttling
+    #   MetricsCollector.record_throttle(statsd, remaining: 5, delay: 1.5)
+    #
+    def record_throttle(backend, remaining:, delay:)
+      increment(backend, RATE_LIMIT_THROTTLE)
+      gauge(backend, "sec_api.rate_limit.remaining", remaining)
+      histogram(backend, "sec_api.rate_limit.delay_ms", (delay * 1000).round)
+    end
+
+    # Records a streaming filing received.
+    #
+    # @param backend [Object] Metrics backend
+    # @param latency_ms [Integer] Filing delivery latency in milliseconds
+    # @param form_type [String] Filing form type (10-K, 8-K, etc.)
+    # @return [void]
+    #
+    # @example Record a filing receipt
+    #   MetricsCollector.record_filing(statsd, latency_ms: 500, form_type: "10-K")
+    #
+    def record_filing(backend, latency_ms:, form_type:)
+      tags = {form_type: form_type}
+      increment(backend, STREAM_FILINGS, tags: tags)
+      histogram(backend, STREAM_LATENCY, latency_ms, tags: tags)
+    end
+
+    # Records a stream reconnection.
+    #
+    # @param backend [Object] Metrics backend
+    # @param attempt_count [Integer] Number of reconnection attempts
+    # @param downtime_seconds [Float] Total downtime in seconds
+    # @return [void]
+    #
+    # @example Record a reconnection
+    #   MetricsCollector.record_reconnect(statsd, attempt_count: 3, downtime_seconds: 15.5)
+    #
+    def record_reconnect(backend, attempt_count:, downtime_seconds:)
+      increment(backend, STREAM_RECONNECTS)
+      gauge(backend, "sec_api.stream.reconnect_attempts", attempt_count)
+      histogram(backend, "sec_api.stream.downtime_ms", (downtime_seconds * 1000).round)
+    end
+
+    # Records a filing journey stage completion.
+    #
+    # Use this to track duration of individual pipeline stages (detected,
+    # queried, extracted, processed). Combined with FilingJourney logging,
+    # this provides both detailed logs and aggregated metrics.
+    #
+    # @param backend [Object] Metrics backend
+    # @param stage [String] Journey stage (detected, queried, extracted, processed)
+    # @param duration_ms [Integer] Stage duration in milliseconds
+    # @param form_type [String, nil] Filing form type (10-K, 8-K, etc.)
+    # @return [void]
+    #
+    # @example Record a query stage
+    #   MetricsCollector.record_journey_stage(statsd,
+    #     stage: "queried",
+    #     duration_ms: 150,
+    #     form_type: "10-K"
+    #   )
+    #
+    # @see FilingJourney
+    #
+    def record_journey_stage(backend, stage:, duration_ms:, form_type: nil)
+      tags = {stage: stage}
+      tags[:form_type] = form_type if form_type
+      histogram(backend, JOURNEY_STAGE_DURATION, duration_ms, tags: tags)
+    end
+
+    # Records total filing journey duration.
+    #
+    # Use this to track end-to-end pipeline latency from filing detection
+    # through processing completion. Useful for monitoring SLAs and
+    # identifying slow pipelines.
+    #
+    # @param backend [Object] Metrics backend
+    # @param total_ms [Integer] Total pipeline duration in milliseconds
+    # @param form_type [String, nil] Filing form type (10-K, 8-K, etc.)
+    # @param success [Boolean] Whether processing succeeded (default: true)
+    # @return [void]
+    #
+    # @example Record successful pipeline
+    #   MetricsCollector.record_journey_total(statsd,
+    #     total_ms: 5000,
+    #     form_type: "10-K",
+    #     success: true
+    #   )
+    #
+    # @example Record failed pipeline
+    #   MetricsCollector.record_journey_total(statsd,
+    #     total_ms: 500,
+    #     form_type: "10-K",
+    #     success: false
+    #   )
+    #
+    # @see FilingJourney
+    #
+    def record_journey_total(backend, total_ms:, form_type: nil, success: true)
+      tags = {success: success.to_s}
+      tags[:form_type] = form_type if form_type
+      histogram(backend, JOURNEY_TOTAL_DURATION, total_ms, tags: tags)
+    end
+
+    private
+
+    # Increment a counter metric.
+    #
+    # Supports both statsd-ruby (no tags) and dogstatsd-ruby (with tags) interfaces.
+    # Falls back to no-tag call if backend doesn't support tags.
+    #
+    # @param backend [Object] Metrics backend
+    # @param metric [String] Metric name
+    # @param tags [Hash] Tags to include (optional)
+    # @return [void]
+    # @api private
+    def increment(backend, metric, tags: {})
+      return unless backend
+      return unless backend.respond_to?(:increment)
+
+      if tags.any? && supports_tags?(backend, :increment)
+        backend.increment(metric, tags: format_tags(tags))
+      else
+        backend.increment(metric)
+      end
+    rescue
+      # Don't let metrics errors break operations
+    end
+
+    # Record a histogram/timing metric.
+    #
+    # Falls back to timing method if histogram is not available.
+    #
+    # @param backend [Object] Metrics backend
+    # @param metric [String] Metric name
+    # @param value [Numeric] Value to record
+    # @param tags [Hash] Tags to include (optional)
+    # @return [void]
+    # @api private
+    def histogram(backend, metric, value, tags: {})
+      return unless backend
+
+      if backend.respond_to?(:histogram)
+        if tags.any? && supports_tags?(backend, :histogram)
+          backend.histogram(metric, value, tags: format_tags(tags))
+        else
+          backend.histogram(metric, value)
+        end
+      elsif backend.respond_to?(:timing)
+        backend.timing(metric, value)
+      end
+    rescue
+      # Don't let metrics errors break operations
+    end
+
+    # Record a gauge metric.
+    #
+    # @param backend [Object] Metrics backend
+    # @param metric [String] Metric name
+    # @param value [Numeric] Value to record
+    # @param tags [Hash] Tags to include (optional)
+    # @return [void]
+    # @api private
+    def gauge(backend, metric, value, tags: {})
+      return unless backend
+      return unless backend.respond_to?(:gauge)
+
+      if tags.any? && supports_tags?(backend, :gauge)
+        backend.gauge(metric, value, tags: format_tags(tags))
+      else
+        backend.gauge(metric, value)
+      end
+    rescue
+      # Don't let metrics errors break operations
+    end
+
+    # Check if backend method supports tags (arity > minimum required args).
+    #
+    # @param backend [Object] Metrics backend
+    # @param method_name [Symbol] Method name to check
+    # @return [Boolean] True if tags are supported
+    # @api private
+    def supports_tags?(backend, method_name)
+      method = backend.method(method_name)
+      # arity of -1 or -2 means variable args (accepts keyword args)
+      # arity of 1 means only the metric name (no tags)
+      # arity of 2 means metric + value (no tags)
+      method.arity < 0 || method.arity > 2
+    rescue
+      false
+    end
+
+    # Format tags hash as array of "key:value" strings for StatsD/Datadog.
+    #
+    # @param tags [Hash] Tags hash
+    # @return [Array<String>] Formatted tags
+    # @api private
+    def format_tags(tags)
+      tags.map { |k, v| "#{k}:#{v}" }
+    end
+  end
+end

data/lib/sec_api/middleware/error_handler.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module SecApi
+  # Faraday middleware for SEC API operations.
+  #
+  # These middleware classes handle common concerns like error handling,
+  # rate limiting, and instrumentation. They are automatically configured
+  # in the Client's Faraday connection.
+  #
+  # @see SecApi::Middleware::ErrorHandler HTTP error to exception conversion
+  # @see SecApi::Middleware::RateLimiter Rate limit tracking and throttling
+  # @see SecApi::Middleware::Instrumentation Request/response instrumentation
+  #
+  module Middleware
+    # Faraday middleware that converts HTTP status codes and Faraday exceptions
+    # into typed SecApi exceptions.
+    #
+    # This middleware maps:
+    # - HTTP 400 → ValidationError (permanent)
+    # - HTTP 401 → AuthenticationError (permanent)
+    # - HTTP 403 → AuthenticationError (permanent)
+    # - HTTP 404 → NotFoundError (permanent)
+    # - HTTP 422 → ValidationError (permanent)
+    # - HTTP 429 → RateLimitError (transient)
+    # - HTTP 5xx → ServerError (transient)
+    # - Faraday::TimeoutError → NetworkError (transient)
+    # - Faraday::ConnectionFailed → NetworkError (transient)
+    # - Faraday::SSLError → NetworkError (transient)
+    #
+    # Position in middleware stack: After retry/rate limiter, before adapter
+    #
+    # @raise [ValidationError] when API returns 400 (Bad Request) or 422 (Unprocessable Entity)
+    # @raise [AuthenticationError] when API returns 401 (Unauthorized) or 403 (Forbidden)
+    # @raise [NotFoundError] when API returns 404 (Not Found)
+    # @raise [RateLimitError] when API returns 429 (Too Many Requests)
+    # @raise [ServerError] when API returns 5xx (Server Error)
+    # @raise [NetworkError] when network issues occur (timeout, connection failure, SSL error)
+    class ErrorHandler < Faraday::Middleware
+      # Initializes the error handler middleware.
+      #
+      # @param app [Faraday::Middleware] The next middleware in the stack
+      # @param options [Hash] Configuration options
+      # @option options [SecApi::Config] :config The config object containing on_error callback
+      def initialize(app, options = {})
+        super(app)
+        @config = options[:config]
+      end
+
+      # Processes the request and converts HTTP errors to typed exceptions.
+      #
+      # @param env [Faraday::Env] The request/response environment
+      # @return [Faraday::Response] The response (if no error)
+      # @raise [ValidationError] when API returns 400 or 422
+      # @raise [AuthenticationError] when API returns 401 or 403
+      # @raise [NotFoundError] when API returns 404
+      # @raise [RateLimitError] when API returns 429
+      # @raise [ServerError] when API returns 5xx
+      # @raise [NetworkError] when network issues occur
+      #
+      def call(env)
+        response = @app.call(env)
+        handle_response(response.env)
+        response
+      rescue Faraday::RetriableResponse => e
+        # Faraday retry raises this to signal a retry - we need to re-raise it
+        # so retry middleware can catch it
+        raise e
+      rescue Faraday::TimeoutError => e
+        # Don't invoke on_error here - TransientErrors will be retried.
+        # on_error is invoked by Instrumentation middleware after all retries exhausted.
+        raise NetworkError.new(
+          "Request timeout. " \
+          "Check network connectivity or increase request_timeout in configuration. " \
+          "Original error: #{e.message}.",
+          request_id: env[:request_id]
+        )
+      rescue Faraday::ConnectionFailed => e
+        # Don't invoke on_error here - TransientErrors will be retried.
+        # on_error is invoked by Instrumentation middleware after all retries exhausted.
+        raise NetworkError.new(
+          "Connection failed: #{e.message}. " \
+          "Verify network connectivity and sec-api.io availability. " \
+          "This is a temporary issue that will be retried automatically.",
+          request_id: env[:request_id]
+        )
+      rescue Faraday::SSLError => e
+        # Don't invoke on_error here - TransientErrors will be retried.
+        # on_error is invoked by Instrumentation middleware after all retries exhausted.
+        raise NetworkError.new(
+          "SSL/TLS error: #{e.message}. " \
+          "This may indicate certificate validation issues or secure connection problems. " \
+          "Verify your system's SSL certificates are up to date.",
+          request_id: env[:request_id]
+        )
+      end
+
+      private
+
+      def handle_response(env)
+        # Only handle error responses - skip success responses
+        return if env[:status] >= 200 && env[:status] < 300
+
+        error = build_error_for_status(env)
+        return unless error
+
+        # NOTE: on_error callback is NOT invoked here.
+        # All on_error invocations happen in Instrumentation middleware after the exception
+        # escapes all middleware (including retry). This ensures on_error is called exactly once,
+        # only when the request ultimately fails (after all retries exhausted for TransientError,
+        # or immediately for PermanentError).
+        raise error
+      end
+
+      # Builds the appropriate error for the HTTP status code.
+      #
+      # Error Taxonomy Decision (Architecture ADR-2):
+      # - TransientError (retryable): Network issues, server errors, rate limits - worth retrying
+      #   because the underlying issue may resolve. Supports NFR5: 95%+ automatic recovery.
+      # - PermanentError (fail-fast): Client errors like auth, validation, not found - no point
+      #   retrying because the same request will always fail. Fail immediately to save resources.
+      #
+      # @param env [Faraday::Env] The response environment
+      # @return [SecApi::Error, nil] The appropriate error, or nil for unhandled status
+      def build_error_for_status(env)
+        request_id = env[:request_id]
+
+        case env[:status]
+        # 400/422: PermanentError - Client sent invalid data. Retrying won't help.
+        when 400
+          ValidationError.new(
+            "Bad request (400): The request was malformed or contains invalid parameters. " \
+            "Check your query parameters, ticker symbols, or search criteria.",
+            request_id: request_id
+          )
+        # 401/403: PermanentError - Auth issues need human intervention (fix API key or subscription).
+        # Both map to AuthenticationError because the resolution is the same: fix credentials.
+        when 401
+          AuthenticationError.new(
+            "API authentication failed (401 Unauthorized). " \
+            "Verify your API key in config/secapi.yml or SECAPI_API_KEY environment variable. " \
+            "Get your API key from https://sec-api.io.",
+            request_id: request_id
+          )
+        when 403
+          AuthenticationError.new(
+            "Access forbidden (403): Your API key does not have permission for this resource. " \
+            "Verify your subscription plan at https://sec-api.io or contact support.",
+            request_id: request_id
+          )
+        # 404: PermanentError - Resource doesn't exist. Retrying won't create it.
+        when 404
+          NotFoundError.new(
+            "Resource not found (404): #{env[:url]&.path || "unknown"}. " \
+            "Check ticker symbol, CIK, or filing identifier.",
+            request_id: request_id
+          )
+        when 422
+          ValidationError.new(
+            "Unprocessable entity (422): The request was valid but could not be processed. " \
+            "This may indicate invalid query logic or unsupported parameter combinations.",
+            request_id: request_id
+          )
+        # 429: TransientError - Rate limit will reset. Worth waiting and retrying automatically.
+        # Supports FR5.4: "automatically resume when capacity returns"
+        when 429
+          retry_after = parse_retry_after(env[:response_headers])
+          reset_at = parse_reset_timestamp(env[:response_headers])
+
+          RateLimitError.new(
+            build_rate_limit_message(retry_after, reset_at),
+            retry_after: retry_after,
+            reset_at: reset_at,
+            request_id: request_id
+          )
+        # 5xx: TransientError - Server issues are typically temporary. Retry with backoff.
+        # Supports NFR5: 95%+ automatic recovery from transient failures.
+        when 500..504
+          ServerError.new(
+            "sec-api.io server error (#{env[:status]}). " \
+            "automatic retry attempts exhausted. This may indicate a prolonged outage.",
+            request_id: request_id
+          )
+        end
+      end
+
+      # Parses Retry-After header value (integer seconds or HTTP-date format).
+      #
+      # @param headers [Hash, nil] Response headers
+      # @return [Integer, nil] Seconds to wait, or nil if header not present/invalid
+      def parse_retry_after(headers)
+        return nil unless headers
+
+        value = headers["Retry-After"] || headers["retry-after"]
+        return nil unless value
+
+        # Try integer format first (e.g., "60")
+        Integer(value, 10)
+      rescue ArgumentError
+        # Try HTTP-date format (e.g., "Wed, 07 Jan 2026 12:00:00 GMT")
+        begin
+          http_date = Time.httpdate(value)
+          delay = (http_date - Time.now).to_i
+          [delay, 0].max
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      # Parses X-RateLimit-Reset header to a Time object.
+      #
+      # @param headers [Hash, nil] Response headers
+      # @return [Time, nil] Reset timestamp, or nil if header not present/invalid
+      def parse_reset_timestamp(headers)
+        return nil unless headers
+
+        value = headers["X-RateLimit-Reset"] || headers["x-ratelimit-reset"]
+        return nil unless value
+
+        Time.at(Integer(value, 10))
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # Builds an actionable error message for rate limit errors.
+      #
+      # @param retry_after [Integer, nil] Seconds to wait
+      # @param reset_at [Time, nil] Reset timestamp
+      # @return [String] Formatted error message
+      def build_rate_limit_message(retry_after, reset_at)
+        parts = ["Rate limit exceeded (429 Too Many Requests)."]
+
+        if retry_after
+          parts << "Retry after #{retry_after} seconds."
+        elsif reset_at
+          parts << "Rate limit resets at #{reset_at.utc.strftime("%Y-%m-%d %H:%M:%S UTC")}."
+        end
+
+        parts << "Automatic retry attempts exhausted. Consider implementing backoff or reducing request rate."
+        parts.join(" ")
+      end
+
+      # NOTE: on_error callback is NOT invoked here.
+      # All on_error invocations happen in Instrumentation middleware (first in stack)
+      # after exceptions escape all middleware (including retry). This ensures on_error
+      # is called exactly once, only when the request ultimately fails.
+    end
+  end
+end