Building APIs that behave predictably under duplication is critical. When clients retry requests due to network issues or timeouts, we must prevent duplicate side effects. This is idempotency: identical requests yield identical outcomes after the first execution. I’ve implemented these in payment systems where double-charging causes real harm. Here are seven Ruby techniques I use in Rails applications.

Idempotency keys form the foundation. Clients generate unique keys like UUIDs and send them in headers. Servers use these to track request state. Here’s a robust handler I’ve deployed:

class PaymentController < ApplicationController
  def create
    handler = IdempotencyHandler.new(request)
    result = handler.execute { process_payment(params) }
    render json: result
  end

  private

  def process_payment(payment_params)
    PaymentService.new(payment_params).perform
  end
end

The handler class manages state transitions atomically:

class IdempotencyHandler
  EXPIRY = 12.hours

  def initialize(req)
    @request = req
    @key = req.headers["Idempotency-Key"] || generate_fallback_key(req)
    @store = Rails.cache
  end

  def execute
    return @store.read(@key) if @store.exist?(@key)
    
    @store.write(@key, :processing, expires_in: EXPIRY)
    response = RedisLock.execute(@key) { yield }
    @store.write(@key, response, expires_in: EXPIRY)
    response
  rescue => e
    @store.delete(@key)
    raise PaymentProcessingError, e.message
  end

  private

  def generate_fallback_key(req)
    digest = OpenSSL::Digest::SHA256.new
    data = [req.method, req.path, req.params].join
    digest.hexdigest(data)
  end
end

Request fingerprinting supplements keys when clients omit them. We hash method, path, and parameters to create a fallback identifier. The SHA256 digest ensures uniqueness. In one e-commerce project, this prevented duplicate orders from curl scripts lacking proper headers.

Atomic database operations guarantee single execution. Consider inventory management:

def reserve_inventory(item_id, quantity)
  Inventory.transaction do
    item = Inventory.lock.find(item_id)
    raise InsufficientStock if item.available < quantity
    
    # Atomic update prevents race conditions
    item.update!(
      available: item.available - quantity,
      reserved: item.reserved + quantity
    )
  end
end

The transaction block and row lock ensure concurrent requests process sequentially. I combine this with idempotency keys for distributed systems.

State machines enforce valid transitions. Using the aasm gem:

class Order < ApplicationRecord
  include AASM

  aasm column: :status do
    state :pending, initial: true
    state :processing
    state :shipped
    state :cancelled

    event :process do
      transitions from: :pending, to: :processing
    end

    event :ship do
      transitions from: :processing, to: :shipped
    end

    event :cancel do
      transitions from: [:pending, :processing], to: :cancelled
    end
  end
end

Attempting ship from pending fails gracefully. In logistics APIs, this prevented invalid state jumps during retries.

Distributed locks prevent concurrent processing. Redis works well:

class RedisLock
  def self.execute(key, timeout: 5)
    redis = Redis.new
    lock_key = "lock:#{key}"

    if redis.set(lock_key, 1, nx: true, ex: timeout)
      yield
    else
      raise ConcurrentRequestError
    end
  ensure
    redis.del(lock_key)
  end
end

During a payment gateway integration, this handled simultaneous retries from mobile clients. The lock ensures only one request processes while others wait or fail.

Response caching completes the pattern. Store successful responses:

def execute
  cached = @store.read(@key)
  return cached if cached.present?

  # ... processing logic ...

  @store.write(@key, {
    status: :success,
    data: response_data,
    timestamp: Time.current
  }, expires_in: EXPIRY)
end

Duplicate requests receive identical responses. I include timestamps so clients detect stale data.

Error recovery cleans partial states. For payment processing:

def process_payment
  Payment.transaction do
    charge = create_charge_record
    external_id = PaymentGateway.charge(amount)
    charge.update!(external_id: external_id)
  end
rescue PaymentGateway::Timeout
  retry_after_delay
end

The transaction rolls back on exceptions. We then implement asynchronous verification for timeouts. At a fintech startup, this reduced manual reconciliation by 80%.

These techniques form a defense-in-depth strategy. Keys handle client retries, atomic operations protect data integrity, state machines enforce business rules, and locks coordinate distributed systems. Start with keys and atomic updates—they cover most cases. Add fingerprinting for legacy integration. Reserve locks for high-contention resources. Always test with chaos tools like rails-rake-resilience.

Implementation matters more than theory. Monitor idempotency key usage patterns. Set appropriate expirations—too short causes duplicate processing, too long wastes storage. Log duplicate requests to detect client issues. I once discovered a misbehaving SDK through such logs. Balance strictness with practicality: not every endpoint needs full idempotency.

In production, combine these with idempotent HTTP methods. PUT replaces resources entirely. PATCH requires careful design. POST endpoints benefit most from these techniques. Document your idempotency guarantees clearly in API references. Clients should know when retries are safe.

Building reliable systems requires anticipating failure. Network partitions happen. Clients retry aggressively. With these Ruby techniques, your Rails APIs will handle duplication gracefully. Start small, instrument everything, and iterate. The peace of mind is worth the effort.