---
title: "Idempotent"
slug: "idempotent"
category: "glossary"
tags: ["glossary", "coding", "idempotent", "http", "reliability"]
status: "stable"
last_updated: 2026-05-14
summary: "An idempotent operation produces the same observable state whether it is run once or many times with the same input, which makes retries safe."
related:
  [
    "[[coding/general-principles]]",
    "[[glossary/side-effect]]",
    "[[glossary/immutable-data]]",
    "[[cheatsheets/http-status-codes]]",
    "[[backend/migrations]]",
    "[[ai-agents/structured-output]]",
  ]
---

## Overview

This page is the atomic definition. The general-principles deep-dive lives at [[coding/general-principles]].

## Definition

An idempotent operation produces the same observable state whether it is run once or many times with the same input. In HTTP, `GET`, `PUT`, and `DELETE` are defined as idempotent; `POST` is not. In database work, `INSERT ... ON CONFLICT DO NOTHING` is an idempotent insert. Idempotency is what makes retries safe in distributed systems: a client can replay a request after a timeout without fear of duplicate side effects, as long as it uses an idempotency key the server checks against a history table.

## When it applies

Design API endpoints, background jobs, migrations, and event handlers to be idempotent. Required whenever the network can drop a response or a worker can crash mid-task.

## Example

A payments API accepts an `Idempotency-Key` header; the server records the key with the response. A retried request with the same key returns the original response instead of charging the card again.

## Related concepts

- [[coding/general-principles]] - the broader principles that include idempotency.
- [[glossary/side-effect]] - non-idempotent operations are those whose side effects compound.
- [[glossary/immutable-data]] - immutable inputs make idempotency easier to reason about.
- [[cheatsheets/http-status-codes]] - the HTTP method semantics that define idempotency.
- [[backend/migrations]] - schema migrations must be idempotent to survive partial application.

## Citing this term

> See [[glossary/idempotent|Idempotent]] (llmbestpractices.com/glossary/idempotent).

## Related

- [[coding/general-principles]]
- [[backend/migrations]]
- [[cheatsheets/http-status-codes]]
- [[glossary/side-effect]]
- [[glossary/immutable-data]]