Skip to content

The Request Timed Out. Did the Operation Actually Fail?

4 min read4 views[Backend]
Cover image for "The Request Timed Out. Did the Operation Actually Fail?"

You click Submit. The spinner runs for ten seconds. Then the application says something went wrong and invites you to try again.

That message sounds reasonable. But what went wrong, exactly?

Maybe the request never reached the server. Maybe the server rejected it. Maybe it saved everything successfully and the response disappeared on its way back. Those situations look remarkably similar from the client, and they require different decisions.

A timeout is evidence about how long you waited. It is not a receipt proving that nothing happened.

The failure happens between two successful steps

Imagine an API that creates shipping labels:

Client                         Server
  | POST /labels                  |
  |------------------------------>|
  |                               | Create label
  |                               | Commit transaction
  |      Connection disappears    |
  |<------------- X --------------|
  |                               |
  | Retry POST /labels            |
  |------------------------------>|
  |                               | Create another label?

The first label exists. The client doesn't know its identifier. Retrying the original operation without a way to recognize it can create another label.

Making the timeout longer might reduce how often this happens. It cannot remove the uncertainty. A connection can fail after any amount of waiting.

Idempotency is about effects

An operation is idempotent when repeating it has the same intended effect as performing it once. Setting a preference to dark can have that property. Incrementing a counter usually does not.

HTTP defines methods including PUT and DELETE as idempotent. That doesn't require identical responses: deleting something twice can produce a success followed by a not-found response while leaving the same final state. POST has no general idempotency guarantee, and PATCH is not inherently idempotent either. The operation's actual semantics matter when deciding whether to retry. HTTP semantics, section 9.2.2

This builds on my REST article, with an important clarification: a PATCH that sets a field can be idempotent; a PATCH that increments a value may not be.

Give the logical operation an identity

For a creation endpoint, one practical design is a client-generated idempotency key:

POST /labels
Idempotency-Key: 73bc9e5e-f39c-4fb3-912c-54fcdf4b0031
Content-Type: application/json

{"order_id": 1842, "service": "standard"}

The client creates that key once for this attempt to purchase a label. Retries reuse it. A genuinely new purchase gets a new key.

Generating a fresh UUID inside the retry loop defeats the entire mechanism.

The header alone does nothing. Your server must implement a contract. Stripe's API provides a concrete example of an API accepting an idempotency key; check the provider's documented behavior before assuming that different APIs handle retention or errors identically. Stripe idempotent requests

The database must enforce the promise

For an operation entirely inside one database, I would design the transaction around these requirements:

  1. Authenticate the caller and validate the input.
  2. Claim a key scoped to that caller and operation, with a unique database constraint.
  3. Store a fingerprint of the validated request so the same key cannot silently mean something different.
  4. Perform the business write and record the result in the same transaction.
  5. On a duplicate key, return the recorded result, reject changed input, or report that the operation is still in progress.

A separate “does this key exist?” query followed by an insert is insufficient. Two concurrent requests can both see that it doesn't exist. The constraint and transaction are what make the promise enforceable.

Retention is part of the API contract too. If the server forgets keys after a day, a retry a week later cannot rely on that record to prevent duplication.

External side effects need another boundary

A database transaction cannot roll back a label already purchased from another company's API.

If that external call succeeds and your process crashes before recording success, you're back in uncertainty. Use the provider's deduplication mechanism where available, persist a stable operation identifier, and provide a way to reconcile pending work. A durable job or outbox can preserve intent, but its worker still needs safe handling of repeated delivery.

This is where a tiny retry helper becomes a workflow design problem.

Test the uncomfortable case

Don't test retries only by rejecting requests before the handler runs. Simulate losing the response after the database commits. Send two requests with the same key concurrently. Reuse a key with a different body. Restart the worker between the external effect and the local update.

The UI should also acknowledge uncertainty. “We couldn't confirm the result. Checking status…” can be more accurate than “Failed. Try again.”

Retries are useful. They become reliable when the system can recognize the same work and recover its result, even after the original answer is gone.

# Comments (0)

No comments yet. Be the first.

0/1000