Error Handling

Error Handling

Every non-2xx response and every transport failure raises Cryptohopper::Error. Same idea as the Node/Python/Go/Rust/PHP/Dart SDKs but laid out idiomatically as a single subclass of StandardError with reader attributes.

begin
  ch.hoppers.get(999_999)
rescue Cryptohopper::Error => e
  e.code            # "NOT_FOUND"
  e.status          # 404
  e.message         # human-readable, from the server
  e.server_code     # numeric Cryptohopper code (or nil)
  e.ip_address      # server-reported caller IP (or nil)
  e.retry_after_ms  # only set on 429
end

Cryptohopper::Error extends StandardError, so a bare rescue (or rescue StandardError) will catch it. A bare rescue catching SDK errors and silently moving on is often a footgun — prefer rescue Cryptohopper::Error.

Error code catalog

code	HTTP	When you'll see it	Recover by
VALIDATION_ERROR	400, 422	Missing or malformed parameter	Fix the request; the message says which parameter
UNAUTHORIZED	401	Token missing, wrong, or revoked	Re-auth
DEVICE_UNAUTHORIZED	402	Internal Cryptohopper device-auth flow rejected you	Shouldn't happen via the public API; contact support
FORBIDDEN	403	Scope missing, or IP not allowlisted	Check e.ip_address; add to allowlist or grant the scope
NOT_FOUND	404	Resource or endpoint doesn't exist	Check the ID; check you're using the latest SDK
CONFLICT	409	Resource is in a conflicting state	Cancel the existing job or wait
RATE_LIMITED	429	Bucket exhausted	The SDK auto-retries; see Rate Limits
SERVER_ERROR	500–502, 504	Cryptohopper's end	Retry with back-off; report if persistent
SERVICE_UNAVAILABLE	503	Planned maintenance or downstream outage	Respect retry_after_ms; retry
NETWORK_ERROR	—	DNS failure, TCP reset, TLS handshake failure	Retry; check your network
TIMEOUT	—	Hit the client-side timeout:	Retry; bump timeout if the operation is legitimately slow
UNKNOWN	any	Anything else the SDK didn't recognise	Inspect e.status and e.message

These strings are stable across SDK versions and are also exposed as Cryptohopper::Error::KNOWN_CODES — compare with ==, never substring-match.

Discriminating with a case statement

def categorize(err)
  case err.code
  when "UNAUTHORIZED", "FORBIDDEN", "DEVICE_UNAUTHORIZED"
    :auth
  when "VALIDATION_ERROR"
    :bad_request
  when "NOT_FOUND"
    :not_found
  when "CONFLICT"
    :conflict
  when "RATE_LIMITED"
    :throttled
  when "SERVER_ERROR", "SERVICE_UNAVAILABLE"
    :server
  when "NETWORK_ERROR", "TIMEOUT"
    :transient
  else
    :unknown
  end
end

Future-proof your code by including a :unknown / else branch — the server can return codes the SDK doesn't recognise (they pass through as raw strings on e.code).

A robust retry wrapper

TRANSIENT_CODES = %w[SERVER_ERROR SERVICE_UNAVAILABLE NETWORK_ERROR TIMEOUT].freeze

def with_retry(max_attempts: 5, base_ms: 500)
  attempt = 1
  begin
    yield
  rescue Cryptohopper::Error => e
    raise unless TRANSIENT_CODES.include?(e.code) && attempt < max_attempts

    wait_ms = e.retry_after_ms || base_ms * 2**(attempt - 1)
    sleep(wait_ms / 1000.0)
    attempt += 1
    retry
  end
end

with_retry { ch.hoppers.list }

Don't include RATE_LIMITED in TRANSIENT_CODES — the SDK already retries 429s internally. Wrapping it here would multiply attempts unhelpfully.

Structured logging

For Rails (Rails.logger) or semantic_logger / lograge / dry-logger, pull individual fields:

rescue Cryptohopper::Error => e
  Rails.logger.error(
    event: "cryptohopper_error",
    code: e.code,
    status: e.status,
    server_code: e.server_code,
    ip: e.ip_address,
    retry_after_ms: e.retry_after_ms,
    message: e.message,
  )
end

Sentry / Bugsnag / Honeybadger

When reporting to an exception tracker, attach the SDK's metadata as context so it's queryable in the dashboard. Example with Sentry:

rescue Cryptohopper::Error => e
  Sentry.set_context("cryptohopper", {
    code: e.code,
    status: e.status,
    server_code: e.server_code,
    ip_address: e.ip_address,
  })
  Sentry.capture_exception(e)
  raise
end

This lets you filter Sentry events by cryptohopper.code to see, e.g., a spike of RATE_LIMITED after a deploy.

Distinguishing transient from fatal

A common pattern is "retry only what's worth retrying":

RETRYABLE = %w[SERVER_ERROR SERVICE_UNAVAILABLE NETWORK_ERROR TIMEOUT].freeze
FATAL     = %w[UNAUTHORIZED FORBIDDEN VALIDATION_ERROR NOT_FOUND CONFLICT].freeze

rescue Cryptohopper::Error => e
  if RETRYABLE.include?(e.code)
    enqueue_retry_later(...)
  elsif FATAL.include?(e.code)
    Rails.logger.warn("fatal cryptohopper error: #{e.code}")
    notify_user(e.message)
  else
    # RATE_LIMITED gets here only if SDK retries exhausted
    # UNKNOWN catches anything new the server returns
    raise
  end
end

Idle-machine truthiness gotcha

Cryptohopper::Error instances respond to present? (Rails) as truthy and blank? as falsy — but inside a begin/rescue block, e is always non-nil. Don't write if e.present? to check whether a request failed; use the begin/rescue/else pattern:

begin
  result = ch.hoppers.list
rescue Cryptohopper::Error => e
  handle_error(e)
else
  process(result)  # only runs when no exception
end