Idempotency ensures that no matter how many times you invoke the same operation with the same parameters, you are guaranteed the same end result. This is especially useful for sensitive operations that could involve potential money loss or a poor experience for customers in scenarios such as unintended duplicated charges or payouts to a bank account.
Belvo Direct Debit and idempotency
With Belvo's Direct Debit product, you can provide an Idempotency-Key in the headers of an HTTP request to mitigate the risk of duplicated calls to a resource. We recommend using a generated UUID as the key.
Supported methods
At present, the following API calls support idempotency keys:
Lifecycle of an idempotency key
After a successful API call (with a 200 or 201 HTTP status code), our system caches the response alongside its corresponding idempotency key. Any repeated requests using this key within a 24-hour window fetch the cached result instead of re-executing the operation.
Expiration policy
Idempotency keys have a 24-hour Time-To-Live (TTL) after the initial request timestamp. After this period has passed, a reused key is treated as a new request, invoking a fresh operation and storing the new response.
Idempotency error messages
You will receive an error related to your idempotency key in the following cases:
| Case | Description | HTTP code | Error message |
|---|---|---|---|
| Concurrent Key Use | You send the same idempotency key for concurrent requests | 400 | Concurrent use of idempotency key |
| Changing Request Parameters | You make a request with an unexpired key with a different payload from the initial request. | 400 | Different input for unexpired idempotency key |