- New error class hierarchy under `GetStreamRuby`:

* `StreamError < StandardError`. Abstract base for every SDK-raised exception.

* `ApiError < StreamError`. Raised on any HTTP 4xx/5xx, and on responses whose body cannot be parsed as the canonical `APIError` envelope. Exposes `status_code`, `code`, `message`, `exception_fields`, `unrecoverable`, `raw_response_body`, `more_info`, `details`. Previously only `message` survived.

* `RateLimitError < ApiError`. Raised on HTTP 429. Adds `retry_after` (Float seconds, nil when the header is absent). Parses the `Retry-After` response header per RFC 7231 in both integer-seconds and HTTP-date forms. Past HTTP-dates clamp to 0.

* `TransportError < StreamError`. Raised when no HTTP response is received (connection reset, timeout, TLS handshake failure, DNS failure). Exposes `error_type` from the enum `connection_reset`, `timeout`, `dns_failure`, `tls_handshake_failed`, `unknown`. Always raised inside the matching `rescue Faraday::Error` block, so `Exception#cause` is set to the underlying Faraday error.

* `TaskError < StreamError`. Raised by `wait_for_task` when an async task finishes with `status="failed"`. Exposes `task_id`, `error_type`, `description`, `stack_trace`, `version`.

- New `Client#wait_for_task(task_id, poll_interval: 1, timeout: 60)` helper. Polls `/api/v2/tasks/:id` and: returns the task `result` payload when status reaches `completed`; raises `TaskError` when status reaches `failed`; raises `TransportError` with `error_type: "timeout"` when the deadline elapses.

- `Client#post` (and the multipart upload path) now deserialize the full canonical `APIError` envelope (`code`, `message`, `exception_fields`, `more_info`, `StatusCode`, `details`, `unrecoverable`, `duration`) and populate the new `ApiError` attributes.

- The old `GetStreamRuby::APIError` constant remains as a deprecated alias for `GetStreamRuby::ApiError` for one minor cycle, slated for removal in v9.0. First access emits a one-time `Kernel.warn` deprecation notice.

- The old `GetStreamRuby::Error` constant is preserved as an alias for `StreamError`. Existing `rescue GetStreamRuby::Error` clauses continue to match.

- Pre-flight multipart validation (`file name must be provided`, `file not found`) now raises `ArgumentError` instead of the old `APIError`. These are caller-side programming errors and don't belong on the API-error surface.

require_relative 'generated/models/api_error'

require_relative 'error_mapping'

# Polls the task-status endpoint until the task reaches a terminal state.

#

# Behaviour:

# - status="completed": returns the task `result` payload.

# - status="failed": raises `TaskError` populated from the task's

# `ErrorResult` (`type`, `description`, `stacktrace`,

# `version`).

# - timeout elapsed: raises `TransportError` with `error_type:

# "timeout"`.

#

# @param task_id [String]

# @param poll_interval [Numeric] seconds between polls (default 1)

# @param timeout [Numeric] max seconds to wait (default 60)

# @return [Object] the task `result` payload on success

# @raise [TaskError] when the task reports `status="failed"`

# @raise [TransportError] when the timeout elapses (`error_type="timeout"`)

def wait_for_task(task_id, poll_interval: 1, timeout: 60)

start_time = monotonic_now

loop do

response = common.get_task(task_id)

status = response.status

case status

when 'completed'

return response.result

when 'failed'

raise ErrorMapping.build_task_error(task_id, response.error)

end

if monotonic_now - start_time >= timeout

raise TransportError.new(

"wait_for_task timed out after #{timeout}s for task_id=#{task_id}",

error_type: 'timeout',

)

end

sleep(poll_interval)

end

end

raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))

return StreamResponse.new(response.body) if (200..299).cover?(response.status)

ErrorMapping.raise_api_error(response)

end

def monotonic_now

Process.clock_gettime(Process::CLOCK_MONOTONIC)

raise ArgumentError, 'file name must be provided' if data.file.nil? || data.file.empty?

raise ArgumentError, "file not found: #{file_path}" unless File.exist?(file_path)

raise TransportError.new("Request failed: #{e.message}", error_type: ErrorMapping.classify_faraday_error(e))

require 'json'

require 'time'

module GetStreamRuby

# Translates HTTP responses and Faraday errors into SDK exceptions.

module ErrorMapping

module_function

# Raises the appropriate `ApiError` / `RateLimitError` for a non-2xx

# `Faraday::Response`.

def raise_api_error(response)

parsed_body = parse_error_body(response.body)

raw_body = stringify_body(response.body)

if parsed_body.is_a?(Hash)

api_error = GetStream::Generated::Models::APIError.new(parsed_body)

attrs = api_error_attrs(api_error, response.status, raw_body)

if response.status == 429

raise RateLimitError.new(

retry_after: parse_retry_after(response_header(response, 'Retry-After')),

**attrs,

)

end

raise ApiError.new(**attrs)

end

raise ApiError.new(

message: 'failed to parse error response',

status_code: response.status,

code: 0,

exception_fields: {},

unrecoverable: false,

raw_response_body: raw_body,

more_info: nil,

details: nil,

)

end

def api_error_attrs(model, status, raw_body)

{

message: model.message || "Request failed with status #{status}",

status_code: status,

code: model.code || 0,

exception_fields: model.exception_fields || {},

unrecoverable: model.unrecoverable.nil? ? false : model.unrecoverable,

raw_response_body: raw_body,

more_info: model.more_info,

details: model.details,

}

end

def parse_error_body(body)

return body if body.is_a?(Hash)

return nil unless body.is_a?(String) && !body.empty?

JSON.parse(body)

rescue JSON::ParserError

nil

end

def stringify_body(body)

return '' if body.nil?

return body if body.is_a?(String)

body.to_json

end

def response_header(response, name)

headers = response.headers

return nil if headers.nil?

# Faraday normalizes header names to lowercase, but tolerate either form.

headers[name] || headers[name.downcase] || headers[name.to_s]

end

# Parse Retry-After header. Returns Float seconds. Returns nil when absent or

# unparseable. Past HTTP-dates clamp to 0.

def parse_retry_after(header)

return nil if header.nil?

value = header.to_s.strip

return nil if value.empty?

return value.to_f if value.match?(/\A\d+\z/)

begin

target = Time.httpdate(value)

delta = target - Time.now

delta.negative? ? 0.0 : delta.to_f

rescue ArgumentError

nil

end

end

def classify_faraday_error(error)

case error

when Faraday::TimeoutError

'timeout'

when Faraday::SSLError

'tls_handshake_failed'

when Faraday::ConnectionFailed

classify_connection_failure(error)

else

'unknown'

end

end

def classify_connection_failure(error)

wrapped = error.respond_to?(:wrapped_exception) ? error.wrapped_exception : nil

case wrapped

when SocketError

'dns_failure'

else

'connection_reset'

end

end

def build_task_error(task_id, error_payload)

hash = if error_payload.respond_to?(:to_h)

error_payload.to_h

else

error_payload || {}

end

TaskError.new(

task_id: task_id,

error_type: lookup(hash, :type) || '',

description: lookup(hash, :description) || '',

stack_trace: lookup(hash, :stacktrace),

version: lookup(hash, :version),

)

end

def lookup(hash, key)

hash[key] || hash[key.to_s]

end

end