The Sivo banking APIs support the use of an idempotency key to allow client applications to deal with situations where an error occurs and there is ambiguity on whether the operation executed successfully or not.
A typical scenario is a request to transfer funds, where a response is not received within an expected period of time. Should the operation be retried (risking a duplicate transfer), or should it be skipped (requiring manual intervention or risking a missing transfer)?
By using a unique idempotent key in the request, you tell Sivo that this request is associated with a specific operation. In an uncertain situation you can safely execute the same request with the same idempotent key. Sivo will recognize it, and will execute it again only if the original request failed. If the original request was successful, Sivo will return the result of that operation.
To include an idempotency key in your request you first need to generate a unique string, using the method of your preference. A common approach is to use a v4 UUID. After generating the unique key you can populate it in the Idempotency-Key
header in your request.
Support for idempotency for APIs outside of banking will be coming in the near future. Note that idempotency keys are only applicable to POST
requests that are not inherently idempotent. They do not apply to GET
, UPDATE
or PATCH
requests. They also do not apply to upsert POST
requests, since repeated calls result in the same result.
Reference: IETF Idempotency-Key draft