# Document what makes a command the same command

Transfer the identity, payload-equivalence and retention rules with the endpoint. Callers and operators need the same understanding of a retry.

By Cobnex editorial. Published 2026-09-10. Updated 2026-09-11.

## State the contract with examples

Show a matching retry, a new identical business action and conflicting reuse of a key. Explain which account and operation scope applies to each.

Record the material fields used for equivalence and how defaults are normalised. A later field addition can change the meaning of a request, so the receiving team needs to know when the fingerprint must evolve.

Keep the client responsibility explicit: create one key for an intention and preserve it across the supported retry and recovery paths.

## Transfer the execution and result model

Document pending, completed, rejected and uncertain states, including what callers receive in each. Explain which local transaction or downstream contract protects the effect.

Provide the status lookup and reconciliation procedure for lost responses. Operators should not need to delete request records or invent a new key to discover what happened.

Identify any provider retention or error-caching behaviour the application depends on, with a route to verify current documentation when the integration changes.

## Rehearse the difficult cases

Have the receiving team submit concurrent matching requests, reuse the key with a changed payload and recover a response lost after commit. They should inspect the final target state and returned identifiers.

Include an expired-key scenario and explain the supported action. A long-delayed replay should not be treated as an ordinary immediate retry without checking the contract.

Test account scope and changed permissions so result reuse does not become an access bypass.

## Assign maintenance ownership

Name who owns client key persistence, server equivalence rules, cleanup and downstream reconciliation. These responsibilities can sit in different teams, but the command needs one coherent contract.

Keep regression tests and operational metrics with the endpoint. Review duplicate or missing effects as correctness incidents, while using retry volume as diagnostic context.

A successful handover lets the next team explain why two requests are considered one intention, how that intention reaches one effect and when the protection no longer applies. That shared definition is what keeps retries safe as clients and services evolve.

## Sources

- [AWS Builders' Library: idempotent APIs](https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/)
- [Stripe: idempotent requests](https://docs.stripe.com/api/idempotent_requests)