Idempotency

Idempotency allows safe API retry requests

Idempotency of GET and DELETE requests

Idempotency is a Web API design principle defined as the ability to apply the same operation multiple times without changing the result beyond the first try. The Falu API guarantees the idempotency of GET and DELETE requests, thus, it is always safe to retry them.

Because a certain amount of intermittent failure is to be expected, clients need a way of reconciling failed requests with a server, and idempotency provides this mechanism. Including an idempotency key makes POST requests idempotent, which prompts the API to do the record keeping required to prevent duplicate operations.

Clients can safely retry requests that include an idempotency key as long as the second request occurs within 24 hours from when they first sent the key. For example, if a client request to create a transfer does not elicit a response due to a network connection error, the client can retry the request with the same idempotency key to guarantee that no more than one transfer is created.

Retrying requests using an idempotency key does not change the original result of a request that has completed execution and is most useful for recovering from network errors.

Sending idempotency keys

Idempotency keys are sent in the X-Idempotency-Key header, and should be used for all POST requests to the Falu API. Most official client libraries can send them automatically as long as they're configured to send retries.

If you decide to send them manually, make sure that the tokens being used are sufficiently unique to identify a single operation unambiguously within your account over at least the last 24 hours. Two common strategies for generating idempotency keys are to:

  • Use an algorithm that generates a token with enough randomness, for example, UUID v4.
  • Derive the key from a user-attached object, such as the ID of a transaction. This approach provides a relatively straightforward way to protect against double submissions.

Identify previously executed requests

As explained above, subsequent POST requests with the same idempotency key return the same response/result.

You can identify a previously executed response that's being replayed from the server by the header X-Cached-Response: true.