Ruby SDK

The zeridion-flare gem is published on RubyGems. Zero runtime dependencies — uses stdlib Net::HTTP, OpenSSL, and JSON only.

gem install zeridion-flare

Or add to your Gemfile:

gem "zeridion-flare", "~> 0.1.1"

The ~> 0.1.1 pessimistic-version operator allows patch upgrades (0.1.2, 0.1.3, ...) but holds you on the 0.1.x line — recommended while the SDK is pre-1.0 and a minor bump may carry breaking changes.

Requires: Ruby 3.1+.

Quick start

require "zeridion_flare"

client = Zeridion::Flare::Client.new(api_key: "zf_live_sk_...")
# Or, with FLARE_API_KEY set in the environment:
#   client = Zeridion::Flare::Client.new

job = client.create_job(
  "job_type" => "SendWelcomeEmail",
  "payload"  => { "email" => "alice@example.com" },
  "queue"    => "default",
)

puts job["id"], job["state"]  # "job_abc123", "pending"

Every public method accepts optional idempotency_key: and request_id: keyword arguments, sent as the Idempotency-Key and X-Request-Id headers respectively:

• idempotency_key: — semantic deduplication on the server. A second create_job with the same key returns the original response (status code and body), not a fresh write.
• request_id: — log-correlation hint. Pass your application's trace / correlation ID and grep for it in Zeridion's logs. Omit it and the server returns a generated ULID in the response X-Request-Id header.

Client construction

Keyword	Default	Notes
api_key:	ENV["FLARE_API_KEY"]	Required — pass directly or via env var
base_url:	https://api.zeridion.com	Override for dev / staging
max_retries:	3	Set 0 to disable retries
retry_base_delay_ms:	500	Base for exponential schedule
retry_max_delay_ms:	30_000	Cap on a single backoff wait (and on Retry-After)
timeout_seconds:	30	Per-request timeout
max_response_bytes:	10 * 1024 * 1024 (10 MiB)	Hard cap on response body size; protects against an unbounded body. Set 0 to disable.

Typed error hierarchy

Class	HTTP	When it fires
Zeridion::Flare::Error	—	Base class for every SDK exception
Zeridion::Flare::AuthError	401	Missing / invalid / revoked API key
Zeridion::Flare::QuotaError	402	Daily quota exceeded
Zeridion::Flare::NotFoundError	404	Resource doesn't exist
Zeridion::Flare::ConflictError	409	Idempotency or invalid-state conflict
Zeridion::Flare::RateLimitError	429	Inspect #retry_after, #limit, #remaining

Feature parity

See the SDK overview for the full feature-parity matrix across all 7 official SDKs.

Source

github.com/zeridion/flare-ruby

See also

• Python SDK — closest dynamic-language sibling SDK
• Jobs API — wire-level reference for the endpoints this SDK wraps
• Errors — status codes and error envelopes used by every SDK