Clicked Gallery

What does an Idempotent API mean?

Highlighted from a real engineering doc. Explained by Clicked.

Used in a sentence

Engineering Notes · AI Systems

The payment gateway endpoint must be fully idempotent to ensure multiple clicks don’t double-charge the card.

The reader highlighted one word in the docs. Clicked explained the technical term “idempotent” in plain language:

Explained in three depths

Same facts, different vibe — Slang mode 😎

The Clicked way

●○○

Overview

An idempotent API endpoint produces the same result whether you call it once or ten times, because repeated identical requests don't create duplicate effects. It's the property that stops a double-click from becoming a double-charge.
●○○

Overview

Idempotent means "spam the button all you want, it only counts once." Call it once and the card gets charged; call it ten times because the wifi hiccuped and the card still gets charged once. It's the difference between an API you can retry and an API you fear. 😎

A quick take — often all you need.

●●○

Detail

The problem it solves is that networks fail mid-request. If a payment call times out, the client can't know whether the server processed it, so it retries. Without idempotency that retry might charge the card twice, and with it, retrying is always safe. The standard implementation is an idempotency key: the client attaches a unique ID, the server records the outcome of the first execution under that key, and any repeat with the same key gets the stored response instead of re-executing. Some HTTP methods are idempotent by definition, since deleting something twice still leaves it deleted, while POST is not, which is exactly why payment APIs bolt keys onto it. Every "do not press submit twice" warning on a checkout page is a system admitting it skipped this.
●●○

Detail

Why it exists: the internet is flaky. Request times out, and did it go through? Nobody knows. So clients retry, and retries need to be harmless. The move: send a unique idempotency key with the request, and the server does the work once, saves the receipt under that key, and hands every duplicate the same receipt. Fun spec trivia: GET, PUT and DELETE are idempotent by contract, while POST famously isn't, which is why payment providers make you send keys with it. Every "don't click submit twice!" warning you've ever seen is a confession. 😎

Want more? One click digs deeper.

●●●

Analogy

An elevator button. Press it once or press it seven times while sighing, and one elevator comes, because the request registers once and every repeat maps onto the same outcome. An elevator that dispatched seven cars would be a payment endpoint without idempotency.
Deepest level reached.
●●●

Analogy

It's RSVPing yes to a wedding five times because you're anxious. The couple doesn't set five plates, because it's one seat no matter how many confirmations you send. A payment API should treat your panic-clicks exactly like that host.
Deepest level reached.

Unfamiliar concept? A real-world example makes it click — fresh analogies on tap.

AI explanations may contain errors · Not professional advice

Formal definition — The same term, explained the usual way

Idempotency is the property whereby multiple identical invocations of an operation yield the same system state and response as a single invocation. In HTTP semantics, GET, PUT, and DELETE are defined as idempotent while POST is not; services commonly implement idempotency for non-idempotent operations via client-supplied idempotency keys, under which the outcome of the first execution is persisted and returned for subsequent duplicate requests, thereby rendering retries safe in the presence of network failures.

Want Clicked to explain terms like “idempotent” directly in your browser — including on PDFs?

Add to Chrome — Free

50 free Explanations · No credit card required