> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dialbird.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry write requests with an Idempotency-Key header.

Write endpoints (`POST /contacts`, `POST /messages`) accept an optional `Idempotency-Key` header so you can safely retry a request after a network error without performing the operation twice.

## Using a key

Generate a unique key per logical operation (a UUID works well) and send it on the request. Keys can be up to **255 characters**.

```bash theme={null}
curl -X POST https://app-staging.dialbird.io/api/v1/messages \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c1d9a-1b2c-4d5e-9f01-abcdef123456" \
  -d '{ "to": "+15551234567", "body": "Hello!" }'
```

## Behavior

| Scenario                                             | Result                                                                   |
| ---------------------------------------------------- | ------------------------------------------------------------------------ |
| Retry with the **same key and identical body**       | The original response is replayed; the operation does **not** run again. |
| Reuse the key with a **different body**              | `409 idempotency_key_reused`.                                            |
| Retry **while the first request is still in flight** | `409 idempotency_in_progress`.                                           |

Keys are retained for **24 hours**. After that, the same key is treated as new.

<Tip>
  Derive the key from a stable identifier in your own system (for example, an order id or message draft id) so retries from any part of your code reuse the same key.
</Tip>

## Handling conflicts

A `409` response uses the standard [error envelope](/concepts/errors). On `idempotency_in_progress`, wait briefly and retry the same request — the original will have completed and its response will be replayed.