Synctera.Idempotency (Synctera v1.0.0)

Copy Markdown View Source

Synctera has two distinct idempotency behaviors (docs: "Need to Know" -> Idempotency):

  • :standard — the key is optional. A repeated request with the same key returns the original cached response (incl. status code) for 7 days. Safe to auto-generate and auto-retry.

  • :ledger — applies to money-movement endpoints (ACH, wires, internal transfers, and anything else that posts to the ledger). The key is REQUIRED — Synctera returns 400 if it's missing. A repeat with the same key is NEVER served from cache: it's rejected with 409 (IDEMPOTENCY_CONCURRENT_USE) or 422 (IDEMPOTENCY_INVALID_REUSE), and keys are retained indefinitely per resource. Because a silent retry here fails loudly by design instead of replaying safely, this client does not auto-generate keys for ledger calls unless the caller opts in via auto_generate_ledger_idempotency_keys: true on the client.

Summary

Functions

Generates a random UUID v4 string, suitable as an idempotency key.

Resolves the Idempotency-Key header value to send, given the endpoint's tier, an optional caller-supplied key, and whether the client is configured to auto-generate keys for ledger endpoints.

Types

tier()

@type tier() :: :none | :standard | :ledger

Functions

generate_key()

@spec generate_key() :: String.t()

Generates a random UUID v4 string, suitable as an idempotency key.

resolve_key(tier, supplied_key, auto_generate_for_ledger? \\ false)

@spec resolve_key(tier(), String.t() | nil, boolean()) :: String.t() | nil

Resolves the Idempotency-Key header value to send, given the endpoint's tier, an optional caller-supplied key, and whether the client is configured to auto-generate keys for ledger endpoints.

Raises Synctera.UsageError if a key is required but neither supplied nor auto-generatable, or if a key was supplied for a :none-tier endpoint.