Idempotency

For certain POST endpoints, the API uses client-supplied idempotency keys to ensure that requests can be retried safely without performing the same operation twice. Repeated calls to those endpoints with the same idempotency key will return the cached response from the first call.

The recommended approach for interacting with such endpoints is as follows:

  1. Create a unique, random key, such as a UUIDv4.

  2. Store the intent to call an endpoint along with the generated key in the client database.

  3. Flush to disk (e.g. commit an SQL transaction).

  4. Perform the call to the endpoint.

This ensures that even if the response from the API to a client gets lost, or the client experiences any sort of outage between steps 3 and 4, the client can always safely retry the same action.

If you already have objects corresponding to tasks in the Cashlink API in your client-side database, you can use their internal IDs as idempotency keys!