A timeout does not tell a caller whether an operation failed. The server may have committed a mutation and lost the response. Retrying with a new identity can then create a second resource or apply a second charge.

In Making retries safe with idempotent APIs, Amazon describes caller-provided request identifiers, atomic recording of intent with mutations, and semantically equivalent retry responses. Those are useful building blocks for an API contract. The following example is a design exercise for a reservation service.

Identify intent rather than payload similarity

Suppose a customer reserves two identical seats in separate operations. A hash of the request body would confuse those valid operations with duplicates. Instead, the caller creates a new operation key for each intended reservation and reuses that key for retries of that reservation.

Scope the key to the authenticated customer. Store the normalized request parameters alongside it, and reject reuse with conflicting parameters. Otherwise a client bug could silently return the outcome of an unrelated operation.

A proposed idempotency contract for mutations stored in one transactional database. External effects need additional coordination.

A proposed idempotency contract for mutations stored in one transactional database. External effects need additional coordination.

Make the database boundary explicit

If reservations and operation records live in one database, a transaction can claim a unique customer/key pair, create the reservation, and store its result together. A concurrent duplicate must wait for or observe the winning transaction, then return the stored outcome. A separate check followed by a separate insert leaves a race.

An external payment call changes the problem. The database transaction cannot atomically commit a remote provider’s state. Use a provider-supported idempotency key and a durable state machine for the payment step. A transactional outbox can reliably publish intent, but its consumer still needs duplicate handling.

Failure point Desired retry behavior
Before transaction commit Retry may perform the operation
After commit, before response Return the committed result
Concurrent duplicate Observe one winning operation
Same key, different parameters Return an explicit conflict

Retention is part of the API

An operation key has a memory horizon. If the service discards its record after an hour but clients retry after a day, an old operation may execute again. Document the valid retry interval and choose retention around real client behavior, delayed messages, and resource lifetimes.

I would exercise the contract by dropping responses after commit, racing duplicate requests, and replaying an old request near the retention boundary. Each test should check the number of business mutations, rather than merely checking HTTP status codes.

The design goal is precise: one intended effect within a documented scope and time window, with a response that lets the caller recover from uncertainty.

Related reading: Testing service boundaries with Testcontainers.

Archive note: added November 18, 2026, and filed under 2026-01 as part of the systems reading series.