The Recall API supports idempotency for all requests with the following methods:

PUT
POST
PATCH

This allows you to retry requests that fail due to networking issues without fear of the the action happening multiple times.

What are idempotency keys?

Idempotency keys are a mechanism to prevent accidental duplicate operations by ensuring that repeated requests with the same key are not re-executed.

When our API receives a request containing an idempotency key, it checks whether that key has already been processed for the same HTTP method & endpoint. If it has, the server immediately returns the original response from cache instead of running the action again.

When to use idempotency keys

The primary use cases for idempotency keys include any scenario where a client is unsure whether a previous request actually succeeded. For example:

There's a transient network failure and you don't receive a response
A network timeout occurs while creating a resource

By resending the request with the same key, you can be confident that only one resource is created, without knowing whether or not the first action actually succeeded or not.

📘
Idempotency is not the same as deduplication keys
Idempotency and deduplication keys are separate concepts and should be treated as such.
Idempotency ensures that requests always return the same response for a given request whereas deduplication keys ensure that only one entity is created/updated
Idempotency behavior is also finite (i.e. the idempotency key will only work for 1 hour) whereas the deduplication key is indefinite (i.e. will not create duplicate entities no matter how much time passes)

Making an idempotent request

To make an idempotent request, start by generating a idempotency key.

That key will be used in combination with your user, and the path to identify the request. Pass this key in the Idempotency-Key header in your request.

The behavior is as follows:

If the request is the first request, the endpoint action will be performed as expected
If another matching request is currently being processed, the endpoint's action will be skipped and you will get a 409
If another matching request has completed in the previous hour, the endpoint's action will be skipped and you will get the previously completed request's response.

As a best practice, only generate a new key for each distinct logical operation.

If you reuse a key for two different actions (even if they involve the same resource configuration), the second request will be treated as a duplicate, and its original result will be returned without performing the action again.

Non-cached responses

Responses with the following status codes are not cached, so retrying with the same idempotency key will re-attempt the action:

429 (too many requests)
507 (insufficient storage)