backend-idempotency

Backend Idempotency

Purpose

Guarantee exactly-once execution for mutating operations using idempotency keys, enabling safe retries without duplicate side effects. Idempotency is the foundation of reliable distributed systems — without it, network retries cause duplicate orders, double charges, and inconsistent state.

Agent Protocol

Trigger

Exact user phrases: "idempotency", "idempotent", "idempotency key", "exactly-once", "retry safety", "deduplication", "duplicate detection", "idempotent endpoint", "safe retry".

Input Context

• Which endpoints need idempotency guarantees.
• Existing data store (Redis, PostgreSQL, DynamoDB).
• Current retry configuration.

Output Artifact

Idempotency key handling design. No file unless requested.

Response Format

Endpoint: {method} {path}
Key Source: {client-provided|server-generated}
Storage: {store type}
TTL: {duration}

Completion Criteria

• Idempotency key storage implemented with TTL.
• Key uniqueness enforced at database level.
• Response caching: same key returns same response.
• Expired keys handled gracefully.
• Concurrent requests with same key resolved (first wins or lock).

Max Response Length

4 lines per endpoint. 15 lines for full solution.

Architecture Decision Tree

Which Idempotency Strategy?

Is the operation naturally idempotent? (PUT, DELETE, same result every time)
  ├── Yes → No key needed, just use the resource identifier
  └── No → Is the operation a creation (POST, different result each time)?
            ├── Yes → Client-provided idempotency key required
            │         ├── Does the client always retry on network errors?
            │         │   ├── Yes → Always require key on mutating endpoints
            │         │   └── No → Still require it — clients are unreliable
            │         └── Is the key collision possible?
            │             ├── Yes → Use UUID v4 or v7 for key generation
            │             └── No → Use business key (invoice ID, order number)
            └── No → Server-generated idempotency based on request hash
                      ├── Same request body within TTL → deduplicate
                      └── Different body → new operation