Straddle API

This library provides convenient access to the Straddle API from Ruby.

The full API of this library can be found in api.md.


Contents


Installation

Add the gem to your application's Gemfile:

gem "straddle", "~> 1.0.4" # x-release-please-version

Or install it directly:

gem install straddle


Usage

require "straddle"

client = Straddle::Client.new(
  bearer: ENV["BEARER"], # defaults to the BEARER env var
)

response = client.accounts.retrieve("7c9e6679-7425-40de-944b-e07fc1f90ae7")

puts response.inspect

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.


Authentication

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

Option Type Default Description
bearer `String \ nil` -

Declared schemes:

  • Bearer bearer token


Errors

Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.

begin
  response = client.accounts.retrieve("7c9e6679-7425-40de-944b-e07fc1f90ae7")

  puts response.inspect
rescue Straddle::Errors::APIError => error
  puts "#{error.status}: #{error.message}"
  raise
end

Documented error statuses: 400, 401, 403, 404, 422, 500.


Client Options

Configure the generated client by setting any of these options when you create it.

require "straddle"

client = Straddle::Client.new(
  timeout: 60.0,
  max_retries: 2,
)
Option Type Default Description
bearer `String \ nil` ENV["BEARER"]
webhook_secret `String \ nil` ENV["STRADDLE_WEBHOOK_SECRET"]
base_url `String \ nil` ENV["STRADDLE_BASE_URL"]
max_retries Integer 2 Max number of retries to attempt after a failed retryable request.
timeout Float 60.0 Seconds to wait for a response before timing out.
initial_retry_delay Float 0.5 Seconds to wait before the first retry; later retries back off exponentially.
max_retry_delay Float 8.0 Upper bound, in seconds, on the delay between retries.


Request Options

Option Type Default Description
idempotency_key String - Idempotency key for one request, sent when the SDK configures an idempotency header.
extra_query Hash - Additional query parameters for one request.
extra_headers Hash - Additional headers for one request.
extra_body Hash - Additional body fields for one request.
max_retries Integer - Override retry count for one request.
timeout Float - Override timeout for one request.


Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.


Helpers

  • Every model is a BaseModel: pass a plain hash or a model instance, and read decoded values back as attributes.
  • The gem ships rbi/ and sig/ trees, so Sorbet and Steep type-check calls into the SDK.


Requirements

  • Ruby >= 3.2

Powered by Scalar.