Skip to content
Prompt Words
History

Idempotent request

Also called: idempotency, idempotency key, safe to retry.

A request you can send twice, or ten times, with the same result as sending it once. For payments, the client sends a unique idempotency key, and for a repeated key the server returns the saved first answer instead of charging again.

The first reply gets lost, so the app sends the payment again. With an Idempotency-Key the server sends back its saved reply; without one it charges the card again.

Card charged 0 times

Nothing paid yet.

    Idle

    Say it in a prompt

    Make POST /api/orders idempotent. The client creates one UUID per checkout and sends it in an Idempotency-Key header. Before creating the order, the server reserves the key with a unique insert (in progress), then saves the response status and body with it for 24 hours. The same key again gets the saved response, a key still in progress gets 409 Conflict, and the same key with a different body gets 422.

    Vague vs precise prompt

    Vague prompt

    make the payment endpoint safe to retry

    Typical resultWraps the call in try/catch and retries it. When the first try actually went through but the answer was lost, the retry charges the card a second time.

    Precise prompt

    Make POST /payments idempotent: require an Idempotency-Key header, reserve the key with a unique insert before charging, store the response with it for 24 hours, and return the stored response for a repeated key.

    Typical resultA repeated request gets the first response back, and the card is charged once, however many times the app retries.

    Seen on

    • Stripe API: POST requests accept an Idempotency-Key header; Stripe saves the first result for that key, returns it for repeats, and may remove keys after 24 hours.

    You might describe it as

    • customer got charged twice when they double clicked pay
    • safe to send the same request again after a timeout
    • pressing submit twice should only create one order

    Not to be confused with

    • Retry with backoff

      An idempotent request makes a repeat harmless; retry with backoff is what sends the repeat.

    • Upsert

      An idempotent request makes a whole API call safe to repeat; an upsert is one database write that inserts or updates a row by its key.