Idempotency & Retries - Travelbase Documentation

Critical for write operations that involves Flight booking Idempotency guarantees that the same request executed multiple times produces exactly the same result — no side effects, no duplicate actions, no inconsistent state.

Why It Matters

Distributed systems are unreliable by nature. Network failures, timeouts, and unexpected retries are not edge cases — they are inevitable. Without idempotency, any of the following can silently corrupt your data:

Duplicate Bookings

A retry creates two reservations for the same user on the same slot.

Double Charges

A payment request retried after a timeout bills the customer twice.

Inconsistent State

Partial writes leave your database in an undefined, unrecoverable state.

Even a single duplicate transaction in a financial system can trigger compliance issues, failed audits, and customer disputes. Idempotency is non-negotiable.

How It Works

Every mutating request should include an Idempotency-Key header containing a unique, client-generated identifier:

POST /v1/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: e7b8c2d1-4f3a-4c6e-9b0d-2a1f5e8c3d7b

{
  "amount": 5000,
  "currency": "usd",
  "recipient": "acct_1A2B3C4D5E"
}

When the server receives a request, it follows this logic:

Check for existing key

The server looks up the Idempotency-Key in its store.

First-time request

If no match is found, the request is processed normally and the result is persisted alongside the key.

Duplicate request (same payload)

If the key already exists and the payload matches, the original response is returned immediately — no reprocessing.

Duplicate request (different payload)

If the key exists but the payload differs, the server returns a 422 Unprocessable Entity conflict error.

Behavior Reference

Implementation Guide

Generating keys

Always generate keys on the client side, before the request is sent. UUIDs (v4) are the standard choice.

import { v4 as uuidv4 } from "uuid";

const idempotencyKey = uuidv4();
// → "e7b8c2d1-4f3a-4c6e-9b0d-2a1f5e8c3d7b"

Persisting keys

Store the key before you send the request — not after. If your process crashes mid-flight, you need the key available for the retry.

//  Correct order of operations
await db.pendingRequests.create({ key: idempotencyKey, payload });
const response = await api.post("/v1/payments", payload, {
  headers: { "Idempotency-Key": idempotencyKey },
});
await db.pendingRequests.update({ key: idempotencyKey, status: "complete", response });

Retry with backoff

Combine idempotency keys with exponential backoff for safe, automatic retries:

async function postWithRetry(url: string, payload: object, retries = 3) {
  const idempotencyKey = uuidv4();

  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      return await fetch(url, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey, // Same key on every retry
        },
        body: JSON.stringify(payload),
      });
    } catch (err) {
      if (attempt === retries - 1) throw err;
      await sleep(2 ** attempt * 100); // 100ms, 200ms, 400ms…
    }
  }
}

Always reuse the same key across all retry attempts for a single logical operation. Generating a new key on each retry defeats the purpose entirely.

Best Practices

Use UUIDs

Generate a cryptographically random UUID v4 for every new logical operation. Never derive keys from request data.

Persist before sending

Write the key to durable storage before making the request so retries after crashes use the original key.

Scope to one operation

One key = one operation. Never reuse a key for a different action, even if the payload looks similar.

Common Mistakes

Mistake	Why It’s Dangerous	Fix
Reusing keys across different requests	A cached response from operation A is returned for operation B	Generate a fresh UUID per operation
Not persisting keys before sending	A crash between send and store means retries use a new key, causing duplicates	Store the key first, then send
Ignoring `422` conflict errors	Silent data corruption or unintended overwrites	Treat `422` as a hard stop — investigate before retrying
Using sequential IDs as keys	Predictable keys can collide across clients or sessions	Always use UUID v4 or a CSPRNG-generated value
Generating a new key per retry	Each retry is treated as a fresh request, defeating idempotency	One key per logical operation, reused on every retry attempt

Key Expiry & TTL

Idempotency keys are not stored forever. Most systems enforce a TTL (typically 24 hours). After expiry, resubmitting the same key is treated as a brand-new request.

Do not rely on idempotency keys as a long-term deduplication mechanism. For long-lived deduplication, implement application-level checks (e.g., unique constraints in your database).

​Why It Matters

Duplicate Bookings

Double Charges

Inconsistent State

​How It Works

​Behavior Reference

​Implementation Guide

​Generating keys

​Persisting keys

​Retry with backoff

​Best Practices

Use UUIDs

Persist before sending

Scope to one operation

​Common Mistakes

​Key Expiry & TTL

​Related

Why It Matters

How It Works

Behavior Reference

Implementation Guide

Generating keys

Persisting keys

Retry with backoff

Best Practices

Common Mistakes

Key Expiry & TTL

Related