Idempotency & Duplicate Prevention

In distributed systems, transient network timeouts can lead to ambiguous request outcomes: did the server receive the dispatch before the connection dropped, or should the client retry?

GNS supports Idempotency Keys to guarantee that retried requests never cause duplicate message sends or multiple quota deductions.

1. How It Works

1. The client generates a unique UUID v4 and sends it in the Idempotency-Key header:

   Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

2. GNS records the key in Redis with an atomic lock.
3. If a duplicate request arrives with the same key within the 24-hour retention window, GNS does not re-dispatch the message — it immediately returns the original cached response.

2. Dispatching with an Idempotency Key

curl -X POST "https://api.gns.iitdeveloper.com/api/v1/notifications" \
-H "Authorization: Bearer gns_live_sk_..." \
-H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
-H "Content-Type: application/json" \
-d '{
  "channel": "email",
  "recipient": "customer@example.com",
  "subject": "Order #5091 Confirmed",
  "body": "Thank you for your order."
}'

3. Replay Response

When replayed, GNS returns the original payload with an Idempotent-Replay: true header:

{
  "status": "accepted",
  "notification_id": "notif_01J7K3X9AB0C1D2E3F4G5H6J7K",
  "idempotent_replay": true
}