# Idempotency

> Why retrying a provisioning call is safe only with an idempotency key, and how to use one.

Source: https://www.propexecutor.com/docs/idempotency
Whole reference in one file: https://www.propexecutor.com/doc.md

Provisioning an account spends an account credit, and **credits are never refunded** — not on a breach, not on an archive. So a request that times out is a genuine problem: you cannot tell whether it landed, and retrying blind may spend a second batch you can never get back.

An idempotency key removes the doubt. Send one on every provisioning call.

`POST /v1/accounts` · **Planned** · scope `accounts:write`

<!-- curl -->
```bash
curl -X POST https://api.propexecutor.com/v1/accounts \
  -H "Authorization: Bearer $PFX_KEY" \
  -H "Idempotency-Key: 8f14e45f-ea6a-4c1b-9d2f-3b7a9c5e1d40" \
  -H "Content-Type: application/json" \
  -d '{"account_type_id":"0f9c…","quantity":25}'
```

## How it behaves

- **First call** does the work and stores its response against the key.
- **A retry with the same key and the same body** replays the stored response verbatim — the same account numbers, not a second batch. Nothing is charged twice.
- **A retry while the first call is still running** waits for it rather than running alongside it, so two concurrent retries cannot both provision.
- **The same key with a different body** is refused with `409 idempotency_mismatch`. That is a bug in the caller, and returning the first call’s result would hide it.

## Choosing a key

Any unique string up to 255 characters; a UUID v4 is the easy choice. Generate it **before** the first attempt and reuse it for every retry of that same logical operation — a key generated per attempt defeats the entire mechanism.

> **Without a key, a retry double-spends**
> `POST /v1/accounts` without an `Idempotency-Key` is accepted and treated as a brand-new request every time. If your HTTP client retries on timeout by default — most do — provision with a key or turn the retries off.