Why API timeouts create duplicate actions

A timeout is one of the most misunderstood API errors. When a request times out, beginners often assume the server did nothing. That assumption is dangerous. A timeout usually means the client, browser, gateway, proxy, load balancer, mobile app, or frontend code stopped waiting for a response. It does not automatically mean the backend stopped processing the request.

Here is the common duplicate-request timeline:

Safe retries vs unsafe retries

Not every retry has the same risk. A retry for a read-only request is very different from a retry that creates money movement, orders, accounts, tickets, files, or irreversible side effects.

The safest beginner rule is simple: retry read requests more freely, but protect write requests before retrying them. Any request that creates, charges, sends, imports, books, subscribes, or modifies data should have duplicate protection on the server side.

Idempotency keys explained for beginners

An idempotency key is a unique value sent with a request so the backend can recognize repeated attempts of the same intended action. The client can retry with the same key after a timeout. The server checks whether it already processed that key. If yes, it returns the stored result or a safe duplicate response instead of doing the side effect again.

Example request header:

Idempotency-Key: checkout_2026_07_02_user_123_attempt_abc789

The key should represent one intended operation, not one network attempt. That means:

• One checkout attempt should reuse the same idempotency key across retries.
• A new checkout attempt should get a new key.
• A payment retry after a network timeout should use the same key.
• A totally different payment should use a different key.
• The backend, not just the frontend, must enforce the key.

What the backend should store

A strong idempotency implementation stores enough information to decide whether a retry is the same operation and what response to return.

The safest debugging order after a timeout

When duplicate records already happened, do not only ask “Why did the request timeout?” Also ask “Why did the retry create a second side effect?” The timeout is the trigger. Missing duplicate protection is the design problem.

Frontend duplicate prevention helps, but it is not enough

Frontend protections are still useful. They reduce accidental double-clicks, impatient retries, repeated form submissions, and duplicate loading states. But frontend protection is only the first layer. Users can refresh, open two tabs, lose connection, retry from a mobile app, or trigger the same action from another client.

Good frontend protections

• Disable the submit button while the request is in progress.
• Show a clear loading state such as “Creating order…” or “Processing payment…”
• Prevent double-click form submission.
• Use a stable client request ID for one form submission attempt.
• Use AbortController for cancellation, but remember cancellation does not always stop server work already started.
• Avoid automatic retries for dangerous create/payment actions unless idempotency is implemented.
• After a timeout, show “We are checking whether this completed” instead of immediately encouraging another submit.

Example button guard in browser JavaScript:

let isSubmitting = false;

async function submitOrder(orderData) {
  if (isSubmitting) {
    return;
  }

  isSubmitting = true;

  try {
    const response = await fetch("https://api.example.com/v1/orders", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": orderData.idempotencyKey
      },
      body: JSON.stringify(orderData)
    });

    const data = await response.json();

    if (!response.ok) {
      console.error("Order failed:", response.status, data);
      return;
    }

    console.log("Order created:", data);
  } finally {
    isSubmitting = false;
  }
}

Backend duplicate prevention patterns

The backend is where duplicate prevention becomes reliable. The exact implementation depends on the action, but the principle is the same: store a durable record that lets the server recognize repeated attempts and avoid repeating side effects.

Pattern 1: Idempotency key table

This is useful for payments, checkouts, subscriptions, order creation, ticket creation, and any create action where the client may retry after an unknown result.

CREATE TABLE api_idempotency_keys (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  idempotency_key VARCHAR(120) NOT NULL,
  operation VARCHAR(80) NOT NULL,
  request_hash CHAR(64) NOT NULL,
  status VARCHAR(30) NOT NULL,
  response_status INT NULL,
  response_body JSON NULL,
  resource_id VARCHAR(120) NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY unique_user_operation_key (user_id, operation, idempotency_key)
);

Basic backend flow:

1. Receive request with Idempotency-Key.
2. Calculate a hash of the meaningful request body.
3. Try to create a unique idempotency record.
4. If the key already exists with the same hash and completed status, return the stored response.
5. If the key exists with a different hash, reject it as a key misuse problem.
6. If the key is new, process the operation and store the final result.

Pattern 2: Unique business reference

Sometimes the best duplicate guard is a natural business key. For example:

• One order per checkout session ID.
• One payment per payment intent ID.
• One account per normalized email address.
• One import result per file hash and user ID.
• One booking per reservation hold ID.

Example database constraint:

CREATE TABLE orders (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  user_id BIGINT NOT NULL,
  checkout_session_id VARCHAR(120) NOT NULL,
  total_cents INT NOT NULL,
  status VARCHAR(30) NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY unique_checkout_order (user_id, checkout_session_id)
);

Pattern 3: Webhook event log

Webhook providers often retry delivery when your endpoint times out or returns an error. That means your webhook handler should treat duplicate event delivery as normal, not surprising.

CREATE TABLE processed_webhook_events (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  provider VARCHAR(50) NOT NULL,
  event_id VARCHAR(150) NOT NULL,
  processed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  UNIQUE KEY unique_provider_event (provider, event_id)
);

Before processing a webhook side effect, store or check the provider event ID. If the event was already processed, return a success response without repeating the action.

Pattern 4: Pending operation state

For long-running operations, use a pending state instead of making the client wait forever. The first request creates a job or operation record. The client can poll the operation status later.

{
  "operationId": "op_789",
  "status": "processing",
  "message": "Your import has started. Check this operation ID for progress."
}

This pattern is safer for file imports, report generation, AI jobs, large exports, background sync, and slow third-party integrations.

Practical request and response examples

cURL request with an idempotency key

curl -i -X POST "https://api.example.com/v1/orders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: checkout_abc123" \
  --data '{"checkoutSessionId":"cs_123","totalCents":4999}'

fetch request with timeout and idempotency key

This example uses AbortController style timeout logic. The important part is that the idempotency key represents the checkout attempt, not the individual network attempt.

async function postOrderWithTimeout(orderData) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 10000);

  try {
    const response = await fetch("https://api.example.com/v1/orders", {
      method: "POST",
      signal: controller.signal,
      headers: {
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Idempotency-Key": orderData.idempotencyKey
      },
      body: JSON.stringify({
        checkoutSessionId: orderData.checkoutSessionId,
        totalCents: orderData.totalCents
      })
    });

    const data = await response.json();

    return {
      ok: response.ok,
      status: response.status,
      data: data
    };
  } catch (error) {
    if (error.name === "AbortError") {
      return {
        ok: false,
        status: "timeout",
        message: "The request timed out. The server may still complete it."
      };
    }

    throw error;
  } finally {
    clearTimeout(timeoutId);
  }
}

Successful first response

{
  "status": "created",
  "orderId": "ord_123",
  "idempotencyKey": "checkout_abc123"
}

Safe retry response after the first request already succeeded

{
  "status": "already_processed",
  "orderId": "ord_123",
  "idempotencyKey": "checkout_abc123",
  "message": "This checkout attempt was already completed. Returning the original order."
}

Key reused with a different payload

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": "idempotency_key_conflict",
  "message": "This idempotency key was already used with a different request body.",
  "idempotencyKey": "checkout_abc123"
}

A duplicate-safe API should be predictable. If the same key and same payload are retried, return the original result. If the same key is reused for a different payload, reject it clearly.

Retry rules that reduce duplicate damage

Retry logic should be boring, slow, and careful. Aggressive retries can turn one slow backend into a bigger outage, and blind retries can create duplicates.

Simple retry with backoff idea

This example is intentionally conservative. It retries only when the action is marked safe or when you provide an idempotency key for an unsafe action.

async function retryApiRequest(makeRequest, options) {
  const maxAttempts = options.maxAttempts || 3;
  const baseDelayMs = options.baseDelayMs || 500;
  const isSafeToRetry = options.isSafeToRetry === true;

  if (!isSafeToRetry) {
    throw new Error("Unsafe retry blocked. Add idempotency protection first.");
  }

  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const result = await makeRequest();

      if (result.ok) {
        return result;
      }

      if (![429, 500, 502, 503, 504].includes(result.status)) {
        return result;
      }

      lastError = result;
    } catch (error) {
      lastError = error;
    }

    const delay = baseDelayMs * Math.pow(2, attempt - 1);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }

  throw lastError;
}

Design better duplicate and timeout responses

Good API responses make duplicate prevention easier. A vague 500 or “Something went wrong” forces the frontend to guess. A clear response tells the client whether the operation is pending, completed, duplicated, conflicted, or safe to retry.

Clear timeout/pending response

{
  "status": "processing",
  "operationId": "op_123",
  "message": "The request is still being processed. Check the operation status before retrying."
}

Clear duplicate response

{
  "status": "already_processed",
  "resourceId": "ord_123",
  "message": "This request was already completed. Returning the existing result."
}

Real scenarios where duplicate protection matters most

Bad fixes that do not truly prevent duplicates

Copyable duplicate-timeout debugging checklist

Use this note when debugging a duplicate order, payment, ticket, signup, file import, or webhook event after a timeout.

Duplicate API request after timeout debugging note

User action:
Example: create order / payment / signup / support ticket / webhook / file import

Endpoint:
Example: POST /v1/orders

Client:
Browser fetch / Axios / mobile app / server job / webhook provider / WordPress / PHP

Timeout source:
Browser timeout / AbortController / Axios timeout / gateway 504 / proxy timeout / backend timeout / unknown

First request:
Timestamp:
Request ID:
Idempotency key:
User ID:
Request body hash:
Server log found? Yes / No
Side effect completed? Yes / No
Created resource ID:

Retry request:
Timestamp:
Request ID:
Idempotency key:
User ID:
Request body hash:
Server log found? Yes / No
Created resource ID:

Duplicate protection present:
Idempotency key table? Yes / No
Unique database constraint? Yes / No
Provider transaction ID? Yes / No
Webhook event log? Yes / No
File hash or import job ID? Yes / No
Client request ID? Yes / No

Retry behavior:
Automatic retry? Yes / No
User clicked again? Yes / No
Retry used same key? Yes / No
Retry generated new key? Yes / No

Likely root cause:
No server-side duplicate guard / retry used new key / timeout misunderstood / webhook event not logged / missing unique constraint / frontend double submit / gateway timeout but backend continued

Fix plan:
Add server-side duplicate protection.
Reuse the same idempotency key for the same operation.
Return original result for safe duplicate retries.
Return 409 if the same key is reused with a different body.
Improve frontend timeout message.
Add logs for request ID and operation ID.

Related CodeZips tools for this problem

Use these CodeZips tools when you want to turn a timeout, duplicate request, retry problem, or confusing API response into a cleaner debugging workflow.

Technical references used for this guide

This guide is written as a practical debugging workflow, with retry and idempotency behavior checked against HTTP and API documentation.

• MDN Web Docs: HTTP request methods
• MDN Web Docs: Idempotent
• Stripe API Docs: Idempotent requests
• Stripe Engineering: Designing robust and predictable APIs with idempotency
• MDN Web Docs: Retry-After header
• MDN Web Docs: AbortController
• MDN Web Docs: AbortSignal.timeout()