Idempotency Key

The key must be globally unique for every distinct operation intent. It is typically a UUID or ULID generated by the client before the first request. The server uses this key to recognize that a retry is a duplicate of a previously accepted command, not a new, independent instruction.

• Client-side generation: The sender creates the key to avoid a single point of failure.
• Collision resistance: Uses cryptographically random identifiers to prevent accidental overlap.
• Scope: Uniqueness is enforced within the context of a specific resource or command type.

Upon receiving a command with a new key, the server must atomically store the key and the operation's final result in a persistent data store. If the same key arrives again, the server bypasses execution entirely and returns the cached result. This is often implemented using a compare-and-swap operation in a database.

• Persistence: The key-to-result mapping must survive server restarts.
• Atomicity: Prevents race conditions where two identical requests are processed concurrently.
• Result caching: Stores the exact HTTP status code and response body from the first successful execution.

Keys are not stored forever. They have a defined time-to-live (TTL) to manage storage costs. After a successful operation, the key is retained long enough to cover the maximum client retry window. Once expired, a reused key is treated as a new request, which could be dangerous.

• Retry window: Typically 24 hours for user-facing APIs, shorter for machine-to-machine calls.
• Reconciliation: Expired keys require the client to use a separate status-check endpoint instead of re-sending the command.
• Garbage collection: A background process purges expired keys to reclaim space.

For maximum safety, the server should verify that the request payload matches the original call associated with the key. If a retry contains a different payload, it signals a client logic error, not a network glitch. The server must reject this with a 422 Unprocessable Entity error to prevent silent data corruption.

• Hash comparison: The server stores a SHA-256 hash of the original request body.
• Conflict detection: A mismatch indicates a non-idempotent client bug.
• Error transparency: The response clearly states the payload mismatch, aiding debugging.

In heterogeneous fleet orchestration, an idempotency key prevents a robot from executing the same pick-and-place or dock command twice due to a retried HTTP call. The key is passed through the Unified Control API and stored in the Command Queue to deduplicate instructions before they reach the Agent Driver.

• Example: A move_to_waypoint command with key k-123 is sent. The robot's ACK is lost. The retry with k-123 is silently ignored by the orchestrator.
• Safety: Prevents a forklift from attempting to pick up a pallet that has already been moved.
• Integration: The key is logged in the Event Sourcing stream for a complete audit trail.

While related, these are distinct concepts. Idempotency is a guarantee provided by the receiver that multiple identical requests have the same side effect as one. Deduplication is a broader network function that drops duplicate messages based on a window of seen IDs, often without returning a cached result.

• Idempotency: Application-layer contract. Guarantees a response.
• Deduplication: Transport-layer optimization. May silently drop a message.
• Synergy: A message bus with deduplication reduces the load on the application-layer idempotency logic.

An architectural pattern where all state changes are stored as an immutable sequence of events. The event log becomes the source of truth, enabling complete auditability and replay capability.

• Idempotency keys serve as event identifiers to prevent duplicate appends
• Enables reconstruction of fleet state by replaying the event stream
• Provides a natural transaction log for debugging duplicate command issues

A mechanism ensuring that only one process can access a shared resource or execute a critical section at a time. In idempotency implementations, locks guard the key-check-and-execute sequence.

• Prevents race conditions where two identical commands arrive simultaneously
• Often implemented with Redis Redlock or etcd
• Must include TTL to prevent deadlocks if a process crashes while holding the lock

A flow-control mechanism where a consumer signals the producer to slow down when overwhelmed. This prevents message loss and system overload without relying solely on retry-and-deduplicate patterns.

• Reduces the volume of retried commands that need idempotency checks
• Implemented via reactive streams or TCP window sizing
• Complements idempotency by addressing the root cause of duplicate submission