# Idempotency (https://docs.getbeel.com/en/api/idempotency)

Safely retry requests that create or send invoices with the Idempotency-Key header.

A flaky network can lose the response to a request that succeeded. Retrying it blindly could create two drafts or, worse, send the same invoice twice. The `Idempotency-Key` header prevents that.

## How it works [#how-it-works]

Send a unique value (we recommend a UUID v4) in the `Idempotency-Key` header of every `POST` that creates or sends:

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f2-3c5d7e9b0a12"
```

- The first request with a key runs, and its response is stored for **24 hours**.
- If you repeat the same request with the same key, you get the stored response and the operation does not run again.
- If you reuse the key for a different request (another endpoint or body), you get an error instead of a wrong response.

It applies to `POST /invoices` and `POST /invoices/{id}/send`.

## Good practice [#good-practice]

- Generate the key when you decide to perform the operation and store it with the operation, so a retry after a crash reuses it.
- Use a new key for every distinct operation: two invoices, two keys.
- Retry only network errors, `429` and `5xx`. A `4xx` needs fixing, not retrying.

The errors: `409 idempotency_key_in_use` (a request with the same key is still running: retry shortly with the same key), `422 idempotency_key_reused` (key already used for a different request: use a new one), `400 parameter_invalid` with `param: "Idempotency-Key"` (the key must be 1–255 visible ASCII characters). See [Errors](/en/api/errors).

Even without a key, a draft is sent only once: a second send gets `409 invoice_send_in_progress` or `409 invoice_not_draft` before any call to SDI. See [SDI lifecycle](/en/api/sdi-lifecycle#sending-twice-never-creates-a-duplicate).
