# Idempotency

Source: https://parasend.com/docs/idempotency

Networks fail. A request can time out after Parasend has already sent the delivery, and a plain retry would send it twice. To make retries safe, every `POST` carries an `Idempotency-Key` header: a value you choose, unique for each new action.

```bash
curl -X POST "https://api.parasend.com/v1/deliveries" \
  -H "Authorization: Bearer $PARASEND_KEY" \
  -H "Idempotency-Key: 5f0c6a1e-8a3b-4d2e-9c71-2b4f6e8d0a13" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

## How it works

- **First request with a key:** Parasend does the work and keeps the answer for 24 hours.
- **The same key and the same body within 24 hours:** Parasend does nothing new and returns the stored answer, with the header `Idempotent-Replayed: true`.
- **The same key with a different body:** `409 idempotency_key_reused`. A key belongs to one request.
- **No key on a `POST`:** `400 idempotency_key_missing`.

Only successful answers are kept. If the first attempt failed with an error, a retry with the same key runs again, so you can fix a problem and retry.

Keys are kept per account and mode, and per method and path: your keys never meet another customer's, and a key used in test mode does not affect live mode.

## Choosing keys

- 1 to 255 characters of `A–Z`, `a–z`, `0–9`, `_` and `-`. Anything else answers `400 idempotency_key_invalid`.
- A UUID works well. Better still, derive the key from your own record, such as `invoice-2026-114-notice`, so a restart of your system cannot send the same notice twice.
- Make a new key for each new action, and reuse it only to retry that action.

Only `POST` needs a key. `GET`, `PATCH` and `DELETE` requests carry none: repeating one leaves the same result. Our code examples send a key on every `POST`.