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, so it's 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 a mechanism for that. 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 you first sent the key (idempotency keys expire after 24 hours). For example, if a request to create a transfer doesn't respond because of a network connection error, a 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 won't change the original result of a request that's 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 you should use them 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 unambiguously identify a single operation 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, like UUID v4
- Derive the key from a user-attached object like the ID of a transaction. This 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.