In the world of financial services, reliability isn’t just important – it’s expected. When someone makes a payment, transfers money, or sets up a standing order, they trust that it’ll happen once and only once. But the truth is, we should never fully trust the network. Connections drop. Responses time out. Requests can get lost or duplicated. People click the same button more than once. If your system isn’t built with this reality in mind, these seemingly small issues can cause big problems.
That’s where idempotency comes in.
Idempotency is the idea that no matter how many times a client sends the same request, the outcome stays the same. It’s especially critical when dealing with money.
Here’s what can happen without it:
- A customer might get charged twice for their mortgage
- A business might accidentally send the same transfer multiple times
- A standing order could be created twice, causing overdrafts
- You could face regulatory consequences for failing to protect customers
- And worst of all, you lose trust – which is hard to earn back
Even if your backend systems support idempotency, having this check at the API Gateway gives you an added layer of protection. It ensures consistency, catches problems early, and makes the system more resilient overall.
Why idempotency matters in financial APIs
Idempotency means you can send the same request twice – or ten times – and it won’t make a difference after the first one. That’s a big deal in finance, where even one duplicate operation can have serious consequences.
You’ll find it useful for things like:
- Submitting payments (like with UK Open Banking)
- Transferring money between accounts
- Creating standing orders
- Making international payments
In the UK, Open Banking APIs require support for the x-idempotency-key header. If a client includes it, your system must make sure the request only runs once – even if it’s retried.
Clients don’t have to use the key, but if they do, your API has to honour it. That gives clients flexibility while keeping critical actions safe.
How it works at the API gateway
Adding idempotency protection to the API Gateway is a great way to keep things consistent and reliable. It gives you one place to handle duplicate requests, no matter which backend service they’re going to.
Here’s what that might look like:
This setup helps you:
- Block duplicate requests before they reach your backend
- Apply the same logic to all your APIs
- Cut down on wasted processing
- Make idempotency easier to monitor and debug
Implementation basics
The idea is to use two hooks in your API Gateway:
- Post-authentication hook – checks the idempotency key after the client is authenticated, but before the request goes to your backend.
- Response hook – stores the response after it comes back from your backend.
The first hook (post-auth)
- Checks if the request includes an idempotency key
- If not, it lets the request go through
- If yes, it looks up the key in a cache
- If the same request has already been handled, it returns the saved response
- If the key is new, it marks the request to be cached after processing
The second hook (response)
- Runs after a successful response
- Saves the response to the cache using the idempotency key
- Marks the response with a header like X-Idempotent-Replay: true if it’s used again
What can go wrong – and how to handle it
Even with a good setup, there are things to watch out for:
- Two requests with the same key at the same time – You need a way to handle race conditions so only one of them is processed.
- Different payloads using the same key – That should be rejected to avoid confusion or abuse.
- Client timeouts – A client might retry a request that actually succeeded. Idempotency helps ensure you don’t run it again.
- Unclear responses – Clients need to know if they’re getting a fresh response or a replay. Use a custom header for that.
Make sure to log all key usage and only cache confirmed success responses (like HTTP 2xx).
Keeping it secure and trustworthy
Idempotency is also part of your API security story. Here are a few tips:
- Use unique, hard-to-guess idempotency keys (like UUIDs)
- Scope keys per client so they can’t interfere with each other
- Rate-limit requests using the same key to prevent abuse
- Log everything – especially replays – for auditing and compliance
When done right, idempotency helps prevent fraud and makes your platform more trustworthy.
Examples from the real world
Payment via open banking
A payment is submitted. The client doesn’t get a response and retries. Thanks to the idempotency key, the system knows it’s the same request and returns the original response – no second payment happens.
Standing order setup
A customer sets up a £200 monthly standing order. The page crashes. They try again. Only one order is created.
International transfer
A company sends €50,000 overseas. The request times out. Their retry goes through the gateway, which spots the duplicate and prevents the money from being sent twice.
Monitoring what matters
Make sure to track:
- How often requests are replayed
- How many replays come from key collisions
- Which responses were cached and returned
- How long cached responses stay valid
This gives you visibility into what your clients are doing and helps spot problems early.
Wrapping up
Idempotency is a quiet feature with big impact. It protects your customers, your backend systems, and your reputation.
Even if your backend already supports it, handling idempotency at the API Gateway makes life easier and smarter. It’s a cross-cutting concern that benefits every service equally, helping enforce consistent behaviour without relying on individual backend implementations.
- You catch problems before they spread
- You get consistent behaviour across services
- You reduce duplication and simplify reconciliation
This should be viewed as part of a broader defence-in-depth strategy – another layer of protection that safeguards against unpredictable failures, retries, and network errors.
