Guides
SandboxProduction

Understanding idempotency

The Idempotency-Key header ensures that multiple identical requests result in a single operation only, preventing duplicate processing. It's particularly useful for actions that have side-effects, like creating a resource or processing a payment.

Suggest Edits

Usage

  1. For requests that support idempotency, clients should generate a unique Idempotency-Key for each request. The idempotency key should be in UUID format.
  2. In case of a network error or uncertain response, clients can safely retry the request with the same idempotency key without risking to process the operation multiple times.
  3. The server will recognise the key and ensure that only one operation occurs, returning the result of the original operation for subsequent requests with the same key.

📘

UUIDv4

The Fuse API expects the idempotency key to be a valid UUIDv4.

📘

It is important that a distinct key is used for each unique request

Reusing the same idempotency key will cause the subsequent requests to not be executed. Reuse of an idempotency key with a different payload results in an error.

Error Handling

Idemptency errors you may encounter

Status CodeError TypeDetailSolution
400Bad RequestThe Idempotency-Key header has either not been provided or the provided key is not a valid UUID.Provide a valid UUID in the Idempotency-Keyheader
409ConflictA request with the same payload has started but has not yet completed.Wait for the original request to complete. Alternatively you can retry the request which will return the result of the original request once it has completed.
422Unprocessable EntityThe same idempotency key has been provided for a different request payload.Generate a new idempotency key for the request and try again.

Example

curl --request POST \
     --url https://api-sandbox.fuse.me/v1/internal-accounts/d562708f-f1b5-4da1-b9e6-29aca4270dc2/payments \
     --header 'Idempotency-Key: bd9f3c3d-f77a-403c-b9ca-ab156da4f3ed' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer token' \
     --header 'content-type: application/json' \
     --data '
{
	// payload data
}
'

Updated about 1 year ago

What’s Next

Explore the API Reference