# Idempotency And Exactly Once

> Design operations to be safely retryable and handle duplicate execution correctly. Use when building APIs, message consumers, or any operation that may be retried or delivered more than once.

- Skill: `itsual/idempotency-and-exactly-once` (Agent Skill)
- Install (CLI): `npx skillmds@latest add itsual/idempotency-and-exactly-once`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itsual/idempotency-and-exactly-once/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: itsual (https://skillmd.com/u/itsual)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/itsual/idempotency-and-exactly-once

---


# Idempotency and Exactly-Once Semantics

## Overview

In distributed systems, “exactly-once” is hard. Most practical systems aim for at-least-once delivery + idempotent handlers.

## When to Use

- Payment or state-changing APIs
- Message / event consumers
- Any operation that clients or infrastructure may retry

## Techniques

- Idempotency keys
- Natural idempotency (set-based operations, upserts)
- Deduplication stores with appropriate TTLs
- Outbox pattern for reliable publishing
- Transactional messaging where supported

## Principles

- Assume duplicates will happen
- Make the side effects of duplicate execution safe or detectable
- Document the idempotency guarantees of your APIs

## Verification

- Retrying the same request/message does not produce incorrect duplicate effects
- Idempotency behavior is tested