idempotency-review

When to Use

• Payment, order, billing, webhook, or job changes.
• Handlers can receive duplicate requests.
• Workers or external calls can retry.
• Idempotency keys or replay responses are introduced.

When NOT to Use

• Generic CRUD without retry or duplicate execution risk.
• Frontend-only validation.
• Auth-only review without state mutation.

Workflow

1. Identify the operation that must be idempotent.
2. Identify the idempotency key and its scope.
3. Check storage, locking, replay, and expiry behavior.
4. Review partial failure and concurrent duplicate handling.
5. Report unsafe retry and replay risks.

Review Steps

• Confirm key uniqueness by tenant, actor, and operation.
• Check request hash or parameter mismatch handling.
• Verify replay returns the original response when needed.
• Check concurrent first-writer behavior.
• Verify external side effects are not duplicated.
• Confirm expiry, cleanup, and observability are defined.

Constraints

• Do not assume retries are rare.
• Do not rely only on clients for duplicate prevention.
• Do not log raw keys when they contain sensitive data.
• Keep recommendations implementation-neutral.

Expected Outputs

• Idempotency boundary and key scope.
• Duplicate execution risks.
• Required storage or locking guarantees.
• Replay response behavior.
• Tests for retry, concurrency, and partial failure.