For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Contact SupportGet Started
  • Modernfi Developer Hub
    • Overview for Developers
    • Getting Started
  • Topics
    • Using the Sandbox
    • Authentication
    • Account Structure
    • Idempotency
    • Transaction Records and Sweeps
    • Balance Fields
    • Interest
    • Reports
    • Versioning
    • Changelog
  • API Reference
LogoLogo
Contact SupportGet Started
On this page
  • Idempotent Requests
  • Why this matters
  • Idempotency Keys
  • Example
Topics

Idempotency

Was this page helpful?
Previous

Transactions

Next
Built with

Idempotent Requests

When building an integration, network timeouts and retries are inevitable. Idempotency keys protect against duplicate operations. If a request is sent more than once with the same key, ModernFi will recognize it as a retry and return the original response without reprocessing it.

Why this matters

Imagine your application sends a request to add a transaction record for $10,000. ModernFi receives and processes the request, but before responding, the connection times out. Your application retries the request, assuming it failed.

  • If the retry uses the same idempotency key, ModernFi recognizes it as a duplicate and returns the original response. No duplicate transaction is created.
  • If the retry uses a different key or no key at all, ModernFi treats it as a new request and creates a second $10,000 transaction.

Idempotency Keys

An idempotency key is a unique value generated by your application and passed to the server via the Idempotency-Key header. We recommend using V4 UUIDs to avoid collisions. Store the keys your application generates so that retries always send the same key for the same intended operation.

Idempotency keys are currently supported on:

  • Creating an account (POST)
  • Creating a depositor (POST)
  • Creating a transaction record (POST)

Example

The following snippet outlines how to use an idempotency key with the POST /accounts endpoint:

curl
1curl -X POST https://api.modernfi.com/digital-banking/v1/accounts \
2  -H "Idempotency-Key: 5855b0e6-7d75-11ee-b962-0242ac120002" \
3  -d name="test depositor"

Currently, idempotency keys are stored in our system for 24 hours. The Idempotency key is stored in our system if an API endpoint executes successfully (2XX level response status code). If the request conflicts with another request executing concurrently, fails validation, or results in a non-2XX-level error, the idempotent result is not saved in our database. It is safe to retry these requests because we guarantee no resources were created or modified in these circumstances.