Modern web applications frequently interact with APIs that perform critical operations such as payments, order creation, or data updates. One common problem developers encounter is duplicate requests caused by:
- users double-clicking buttons
- unstable internet connections
- automatic retries
- browser refreshes during a request
Without safeguards, these duplicates can lead to serious issues like multiple charges, duplicated orders, or inconsistent data.
To solve this, many modern APIs rely on a concept called idempotency.
What is Idempotency in API Requests?
In simple terms, idempotency means that performing the same operation multiple times produces the same result as performing it once.
In API design, this means that sending the same request multiple times should not create multiple side effects.
This is usually implemented using a unique request identifier called an Idempotency Key.
Example request:
POST /orders
Idempotency-Key: 12345
If the same request is sent again with the same key, the server recognizes it and returns the previously generated response instead of executing the operation again.
Real-World Example: Online Payments
Imagine a user purchasing a product online.
They click “Pay Now”, but the network is slow and the page appears unresponsive.
The user clicks the button again.
Without idempotency, the system might process two payments.
User clicks Pay twice
↓
POST /payments
POST /payments
↓
Two charges are created
With idempotency implemented:
POST /payments
Idempotency-Key: 9ab3...
POST /payments
Idempotency-Key: 9ab3...
The server detects that the request has already been processed and simply returns the same payment result, preventing duplicate charges.
This pattern is widely used in payment platforms like Stripe.
Why Use Idempotency?
Implementing idempotency provides several important advantages.
Prevents Duplicate Operations
Users often double-click buttons or retry operations when something seems slow.
Idempotency ensures the backend processes the action only once.
Enables Safe Retries
Network failures happen frequently in real-world systems.
Idempotency allows clients to retry requests without worrying about unintended side effects.
Improves System Reliability
In distributed systems, retries and failures are normal.
Download the Medium app
Idempotency ensures that repeated requests do not break system consistency.
Better User Experience
Users should not suffer consequences due to technical issues like timeouts or slow networks.
Idempotency protects operations like:
- payments
- orders
- form submissions
- account actions
Implementing Idempotency in Angular Using an HTTP Interceptor
On the frontend, we can support idempotency by automatically attaching an Idempotency-Key header to requests.
Angular provides a perfect mechanism for this: HTTP Interceptors.
The interceptor can:
- Generate an idempotency key
- Store it in sessionStorage
- Attach it to outgoing requests
- Remove it after a successful response
Step 1: Create the Idempotency Interceptor
import { Injectable } from '@angular/core';
import {
HttpEvent,
HttpHandler,
HttpInterceptor,
HttpRequest,
HttpResponse
} from '@angular/common/http';
import { Observable, tap } from 'rxjs';
@Injectable()
export class IdempotencyInterceptor implements HttpInterceptor {
private readonly HEADER = 'Idempotency-Key';
private readonly STORAGE_PREFIX = 'idem_';
intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
if (!['POST', 'PUT', 'PATCH'].includes(req.method)) {
return next.handle(req);
}
const fingerprint = this.createFingerprint(req);
const storageKey = this.STORAGE_PREFIX + fingerprint;
let idempotencyKey = sessionStorage.getItem(storageKey);
if (!idempotencyKey) {
idempotencyKey = this.generateKey();
sessionStorage.setItem(storageKey, idempotencyKey);
}
const clonedRequest = req.clone({
setHeaders: {
[this.HEADER]: idempotencyKey
}
});
return next.handle(clonedRequest).pipe(
tap({
next: (event) => {
if (event instanceof HttpResponse && event.ok) {
sessionStorage.removeItem(storageKey);
}
}
})
);
}
private createFingerprint(req: HttpRequest<any>): string {
const body = req.body ? JSON.stringify(req.body) : '';
return btoa(`${req.method}|${req.urlWithParams}|${body}`);
}
private generateKey(): string {
return crypto.randomUUID();
}
}
Step 2: Register the Interceptor
import { HTTP_INTERCEPTORS } from '@angular/common/http';
import { IdempotencyInterceptor } from './interceptors/idempotency.interceptor';
providers: [
{
provide: HTTP_INTERCEPTORS,
useClass: IdempotencyInterceptor,
multi: true
}
]
Step 3: What Happens During a Request
When Angular sends a request like this:
this.http.post('/api/orders', orderData)
The interceptor automatically adds:
Idempotency-Key: 3f7a8c41-93a0-4b2f-b2a6-8c9f2d1e7c2b
The key is stored in sessionStorage so that retries reuse the same identifier.
After a successful response:
HTTP 200 OK
The stored key is removed.
Final Thoughts
Idempotency is a simple but powerful technique that dramatically improves the reliability of API-driven systems.
It helps prevent:
- duplicate payments
- repeated orders
- inconsistent data
By implementing idempotency using an Angular HTTP interceptor, you can add this protection transparently across your application.
In systems where operations are critical — like payments or orders — this pattern can make the difference between a reliable system and a costly bug.
If you enjoyed this article, feel free to follow me here or connect with me on LinkedIn to stay updated on my real-world web development experiences.
I’d love to hear your thoughts and keep the conversation going!