Contact Us

Idempotency

Idempotent Requests

A request is considered idempotent if the intended effect of multiple identical requests is the effect of a single request. It is recommended that the client application store utilized idempotency keys so that identical requests are sent with the same idempotency key.

Idempotency Keys

An idempotency key is a unique value used by the server to recognize subsequent retries of the same request. The idempotency key is generated by the client and utilized by the server. In this scenario, the client is a user of the ModernFi API, and the server is the location where the ModernFi API is hosted. Clients may generate idempotency keys in whichever way they please, but we suggest using V4 UUIDs, or another entropic string, as to avoid collisions.

Example

Here is an example of why using an idempotency key is important.

  • Imagine that your application sends a request to add a transaction record to the ModernFi network for $10,000
  • ModernFi receives and processes this request, storing the corresponding information in our database and ledgering the appropriate movement of funds
  • Before the ModernFi API is able to respond, the request times out due to high network congestion
  • On the client side, your application retries the same request because you believe that the operation failed

If this subsequent request from the client utilizes the same idempotency key, the ModernFi API will recognize a duplicate request, avoid processing it, and return the initial response to the first request. If this subsequent request from the client utilizes a different idempotency key (or none at all), the ModernFi API will recognize this as a different request, process it, and create an additional transaction record for $10,000.

Using Idempotency Keys

An Idempotency Key is accepted for requests to the following endpoints:

  • Add a depositor (POST)
  • Add a depositor account (POST)
  • Add a transaction record (POST)

These endpoints support idempotency so that developers can safely retry requests while ensuring that resources are only created or updated one time.

🚧

Warning

When creating or updating resources, it is recommended you use an idempotency key.
The ModernFi API supports idempotency using an Idempotency-Key header to protect against duplicate operations.

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

curl -X POST https://api.modernfi.com/depositors \
  -H "Idempotency-Key: 5855b0e6-7d75-11ee-b962-0242ac120002" \
  -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 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.