Idempotent Requests

Idempotency means repeating an action has the same effect as the first instance of the action. i.e. it's safe to perform the action more than once as it's not going to create duplicates or cause confusing or ambiguous records.

When interacting with an HTTP API it is possible that a request is successfully processed and/or the datastore updated, but either an error response or no response is received by the requester due to a connectivity error. In this case the requester may retry the request and accidentally perform the action more than once e.g. creating duplicate records.

In order to prevent this scenario, we recommend using the optional Idempotency header parameter on POST requests. (The Idempotency header parameter is unnecessary for GET and DELETE requests as they are intrinsically idempotent.)

The Idempotency header parameter allows the Send Payments API to determine if the request has previously been executed and if so, avoid executing it again. If the Idempotency parameter is included in the header, then the request MAY be considered idempotent otherwise it MUST NOT be considered idempotent.

In practice, if the Idempotency header parameter is provided, then the Send Payments API will check an internal cache for a request with the same parameters and body. If one exists, then the cached response is returned (regardless of whether the response was an error or not). If a cached request/response is not found, the endpoint will execute the request, send the response and add the record to the cache.

Records are removed from the cache after 24 hours. If you reuse a value for the Idempotency header parameter after 24 hours elapsed since its first use, it will be treated as a new request. Requests that do not include the Idempotency header parameter are not added to the cache and are not idempotent.

You can use any value for the Idempotency header parameter as long as it conforms to the following format:

String up to 36-characters in length using any of:

• upper-case letters
• lower-case letters
• digits from 0 to 9
• characters _+=/
• Conforms to regex: ^[a-zA-Z 0-9-_+=/]*$

You may choose to generate a unique value for the Idempotency header parameter and store this for use with subsequent requests or you may choose to supply your system’s unique identifier for an equivalent object (e.g. an tradingAccountId or paymentTransactionId).

📘

Not Seeing What You're Looking For?

We are always looking to improve our API documentation to ensure Sends systems are easy to understand and quick to build against. If you're struggling to find the answer to a question we either haven't made it easy enough to find the relevant docs or we haven't had a chance to write something up for it yet.

Either way we want to hear from you!

Head over to our Discussion Board and leave us a note. We keep a close eye on this and want to ensure we make these docs as useful as they can be so will jump on any posts quickly.