# Idempotency

> Retry a send without double-sending, using the Idempotency-Key header.

Canonical: https://docs.whabuzz.com/guides/idempotency/

Networks fail between "we sent it" and "you heard back". Add an `Idempotency-Key` header to [`POST /v1/messages`](https://docs.whabuzz.com/api/messages.md#sendMessage) (up to 255 characters, any string you generate, a UUID works) and a retry will not send twice.

```bash
curl -X POST https://api.whabuzz.com/v1/messages \
  -H "Authorization: Bearer $WHABUZZ_KEY" \
  -H "Idempotency-Key: order-48213-shipped" \
  -H "Content-Type: application/json" -d @body.json
```

| Situation | Result |
|---|---|
| First request with the key | Processed normally. The answer is stored for 24 hours. |
| Same key, same body, original finished | The stored answer is replayed with the header `Idempotent-Replayed: true`. Nothing is sent to Meta. |
| Same key, original still running | `409 idempotency_conflict`. Wait and retry. |
| Same key, different body | `422 idempotency_conflict`. Use a new key. |

Do not fire two requests with the same key at the same time.

If WhaBuzz could not reach Meta (`502 meta_unreachable`) the outcome is unknown. That 502 is stored against the key too, so a retry returns the same 502 instead of risking a duplicate. Use a new key only after you have checked, through [`GET /v1/events`](https://docs.whabuzz.com/api/events.md#listEvents) or a `message.status` event, that the first message was not sent.

Batches use `client_ref` for the same purpose; see [Sending messages](https://docs.whabuzz.com/guides/messages.md#batch).