Skip to main content
An API call or operation is idempotent if it produces the same result regardless of how many times it’s executed. This ensures that repeated calls do not cause unintended side effects, protecting against accidental duplicate requests. The Fluz API supports idempotency requests to safeguard against accidental duplication of operations. By using a client-generated, unique idempotency key, the API ensures that the same request is not processed multiple times within a 10-minute window if provided with the same idempotency key.

​
How It Works

When an idempotency key is provided with a request:
  • The server caches the initial response body and its status code.
  • If a duplicate request with the same idempotency key and response code is received, the API will return the cached result instead of re-executing the operation, especially if an error occurs within the operation. This mechanism helps prevent unintended duplicate processing by returning consistent results even in error scenarios.

​
Generating Unique Idempotency Keys

Clients are responsible for creating and refreshing their idempotency keys. To ensure uniqueness:
  • We strongly recommend using V4 UUIDs, which can be generated with libraries such as these: https://github.com/uuidjs/uuid
  • As a best practice, idempotency keys should expire after some time to avoid reuse and ensure the uniqueness of requests. Fluz expires each unique idempotency key after 10 minutes, except where an operation below says otherwise.

​
Clients will need:

  1. An operation to generate and store a new idempotency key
  2. An operation to remove an old key according to the client’s expiration policy

​
Required Operations

Not all API operations require idempotency keys. Fluz requires idempotency for certain critical operations to ensure data consistency for the following operations:
  • purchaseGiftCard (View here)
  • depositCashBalance (View here)
  • sendMoney and cancelMoneySend (View here). Their keys last longer than the 10 minutes above: sendMoney keeps a key tied to its send for good, so use a new key for every send, and repeating a successful cancelMoneySend of the same send with the same key, as the same user, returns the same response for 24 hours.
For these operations, an idempotencyKey input variable is required.

​
Example Input

Fluz requires an idempotency key for this operation.

​
Next steps

Purchase Gift Card

See the idempotency key in action on the most common money-moving mutation.

Address formatting

The other common cause of rejected requests — how to format addresses so they validate the first time.