Idempotency

Idempotency is a critical reliability mechanism in financial infrastructure.

Infrarails supports ledger-scoped idempotency for eligible transaction operations, helping applications avoid duplicate execution when requests are retried.

Why idempotency matters

Consider an application submitting a transfer.

The request reaches the server, and the transaction is created, but the network connection fails before the response reaches the application.

The application cannot immediately determine whether the transaction was created successfully.

Submitting the same financial operation as a completely new request could result in an unintended duplicate.

Idempotency helps address this problem.

Ledger-scoped idempotency

The core ledger model associates idempotency records with both a ledger identifier and an idempotency key.

Conceptually:

Ledger ID + Idempotency Key
             |
             v
       Logical Operation

This means the ledger is part of the idempotency context.

The precise duplicate-detection rules, key retention period, and response behavior must be taken from the deployed API contract.

Generating an idempotency key

Where the API accepts a client-generated key, use a unique identifier for each logical financial operation.

For example, in Node.js:

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();

Generate the identifier once when the logical operation is created.

Store it alongside your application's payment or transaction reference.

Retrying the same operation

When retrying a request, preserve the original idempotency key.

Original request
    |
    +-- Ledger: ledger-001
    +-- Idempotency Key: operation-123
    |
    v
Network timeout
    |
    v
Check existing operation
    |
    v
Retry if appropriate
    |
    +-- Same Ledger
    +-- Same Idempotency Key

Do not generate a new idempotency key simply because the first HTTP request timed out.

Request consistency

A repeated request should represent the same logical operation.

Changing the amount, accounts, currency, or other essential parameters while reusing an idempotency key may result in a conflict or another documented outcome.

Applications should preserve the original request parameters for safe retries.

Idempotency and transaction status

Idempotency and transaction lifecycle management solve different problems.

Idempotency helps prevent unintended duplicate execution.

Transaction status describes the processing outcome of a financial operation.

For example, an idempotent request may still produce a transaction in the PENDING state.

The application must continue tracking the transaction until the required business outcome is established.

Idempotency and concurrency

Applications may accidentally submit the same operation concurrently.

For example:

• A user clicks a payment button multiple times.
• A background job is executed more than once.
• Multiple workers process the same business event.
• A webhook is delivered repeatedly.

A robust integration should coordinate its own operation identifiers and use the API's supported duplicate-prevention mechanism.

Idempotency does not replace application-level concurrency controls.

Example application pattern

import { randomUUID } from "node:crypto";

function createTransferOperation({
  ledgerId,
  sourceAccountId,
  destinationAccountId,
  amount,
}) {
  if (!Number.isSafeInteger(amount) || amount <= 0) {
    throw new Error("Amount must be a positive integer");
  }

  return {
    operationId: randomUUID(),
    ledgerId,
    sourceAccountId,
    destinationAccountId,
    amount,
    status: "CREATED",
  };
}

This example creates an application-level operation record.

The operationId can be persisted and reused as an idempotency key if it meets the requirements of the actual Infrarails API.

It is not an Infrarails transaction request schema.

Unknown outcomes

When an API request times out:

1. Preserve the original operation identifier.
2. Determine whether the server may have received the request.
3. Retrieve the existing operation where supported.
4. Inspect its current status.
5. Retry only when the API contract permits it.
6. Avoid creating a second logical operation until the first outcome is understood.

Best practices

• Generate unique keys for distinct logical operations.
• Reuse the original key for retries.
• Persist operation identifiers before submitting critical requests.
• Keep ledger identifiers consistent.
• Preserve the original operation parameters.
• Check existing transaction status after uncertain outcomes.
• Do not assume that idempotency guarantees successful completion.
• Implement application-level duplicate protection for asynchronous jobs and webhook processing.

Next steps

Continue with Best Practices for production integration guidance.