Idempotency

Idempotency is an important concept when building reliable API integrations.

An operation is idempotent when repeating the same operation does not produce additional effects beyond the intended result.

For infrastructure involving financial transactions, digital assets, or digital vouchers, duplicate prevention is a critical design consideration.

Why idempotency matters

Consider an application submitting a transaction request.

The server receives the request and processes the operation, but the network connection fails before the client receives a response.

The client cannot immediately determine whether the operation succeeded.

If the client sends a completely new request, the operation could be executed again.

An idempotency mechanism can help prevent this outcome.

Idempotency keys

Some APIs support a client-generated idempotency key.

The key identifies a logical operation so repeated requests can be recognized.

A generic request might include:

POST /example-operation
Content-Type: application/json
Idempotency-Key: example-operation-123

This is an illustrative HTTP request. The actual header name, key format, and supported endpoints must be confirmed in the product API reference.

Generating keys

Where client-generated keys are supported, use unique identifiers for distinct logical operations.

A UUID is one common choice.

For example:

const idempotencyKey = crypto.randomUUID();

Generate the key when creating the logical operation, then retain it for retries of that same operation.

Do not generate a new key for each retry.

Request consistency

A repeated request should preserve the original operation's intended parameters.

Reusing an idempotency key with different request data may result in rejection or other documented behavior.

The exact validation rules depend on the API.

Idempotency and retries

A typical workflow is:

1. Generate a unique operation identifier.
2. Construct the request using the documented idempotency mechanism.
3. Submit the request.
4. Store the operation identifier and relevant response.
5. If the outcome is uncertain, check the operation's status where supported.
6. Retry only according to the documented API rules.

Idempotency is not the same as success

An idempotency mechanism does not guarantee that an operation will succeed.

It is intended to help control repeated execution of the same logical request.

Applications must still handle validation failures, rejected operations, and unknown processing outcomes.

Idempotency scope

Idempotency mechanisms may be scoped to a particular account, ledger, tenant, environment, or other resource boundary.

Keys may also have documented retention periods or expiration behavior.

Never assume that a key remains valid indefinitely.

Product-specific behavior

InfraRails

Idempotency is particularly relevant to ledger transactions and other financial state changes.

The InfraRails API reference will define the supported key format, scope, duplicate-request behavior, and applicable operations.

Hyperhash

Blockchain transactions may require additional safeguards involving transaction identifiers, network confirmations, and transaction submission rules.

The Hyperhash API reference will document any supported idempotency behavior.

Foundry

Voucher issuance and redemption workflows may require duplicate-prevention controls.

The Foundry API reference will document the applicable mechanisms when available.

Best practices

• Use unique identifiers for distinct logical operations.
• Preserve the same key for retries of an operation.
• Never assume that a timeout means failure.
• Check existing operation state before creating another operation.
• Store sufficient information for reconciliation.
• Follow product-specific idempotency rules.
• Avoid exposing sensitive transaction information in logs.

Next steps

You have completed the shared Getting Started guides.

Continue with the documentation for your selected platform:

• InfraRails — Financial infrastructure.
• Hyperhash — Blockchain infrastructure.
• Foundry — Voucher infrastructure.

Refer to each platform's API reference for its exact implementation requirements.