Idempotency
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:
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.
