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

# Idempotency

> Retry a call that sends or charges, without it running twice.

A network can lose an answer after the call already ran. Sending that call again could then send a message twice, or pay for an enrichment twice. An `Idempotency-Key` header makes the retry safe: the call runs once, and every retry with the same key gets the first call's answer.

## Send a key

Make a new idempotency key for each operation, such as a UUID, and send it with the first try and with every retry:

```bash theme={null}
curl https://api.outbound.dev/v1/messages \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c9d2e-8a4b-4e7c-9f30-6b2a1d8e4c75" \
  -d '{"channel": "email", "from": "maya@fernway.co", "to": ["ana.costa@example.com"], "subject": "Your Lisbon fleet", "content": "<p>Hi Ana, saw Northwind runs 40 trucks out of Lisbon. Worth a short call?</p>"}'
```

An idempotency key is 1 to 255 visible ASCII characters. Any other value answers `422` `validation_failed`, with `param` set to `Idempotency-Key`.

## Calls that take a key

These calls, which send something or charge for it, take one:

| Call | What a retry could repeat |
| - | - |
| `POST /v1/messages` | A message |
| `POST /v1/conversations/{conversationId}/reply` | A reply |
| `POST /v1/linkedin/invitations` | A LinkedIn invitation |
| `POST /v1/campaigns/{campaignId}/steps/{stepId}/test-email` | A test email |
| `POST /v1/campaigns/{campaignId}/launch` | A launch |
| `POST /v1/people/enrich` | An enrichment, and its charge |
| `POST /v1/people/enrich/batch` | A batch enrichment, and its charge |
| `POST /v1/lists/{listId}/enrich` | A list enrichment, and its charge |
| `POST /v1/emails/verify` | A verification, and its charge |
| `POST /v1/accounts/email` | A mailbox connected, and its fee |
| `POST /v1/accounts/email/bulk` | A mailbox import, and its fees |

Every other route ignores the header.

## How an idempotency key works

* **It belongs to your organization and the route.** A retry sent with another of your API keys is still the same call, and the same idempotency key sent to another route is a different one.
* **It is remembered for 24 hours** from its first call.
* **The same key with the same request** answers the first call's answer again, with the header `Idempotent-Replayed: true`. Nothing is sent or charged again: `X-Charged-Usd` is `0.000000`, and the retry shows in `GET /v1/requests` with `isReplay` true and no cost.
* **The same key with a different request** answers `422` `idempotency_key_reused`. The request is the path, ids included, and the body: the key that launched one campaign cannot launch another. Make a new key for a new operation. A mailbox's password is the one thing not compared.
* **A batch or a list enrichment answers its job as it was when it started.** Read where the job is now with `GET /v1/jobs/{jobId}`.
* **While the first call is still running,** the same key answers `409` `idempotency_in_progress`. Wait a few seconds, then try again with the same key.
* **Only successful answers are remembered.** A refusal, which is any `4xx` and a `429` too, frees the key at once: the same key runs the call again, so a corrected retry works.
* **After a `5xx` the key is held for 5 minutes** from the call's start, because the call may still take effect. A retry in that time answers `409` `idempotency_in_progress`; after it, the same key runs the call again.
* **When a send's outcome cannot be known,** the retry answers `409` `idempotency_outcome_unknown` instead of sending again: the first try of a message, a reply, an invitation or an import failed after it may already have gone out. Check whether it did, then use a new key if it did not.

## Retry a call

**1. Make the idempotency key before the first try**

Keep it with the operation, so a retry after a crash or a restart sends the same one.

**2. Send the call**

A `2xx` is final: the same key answers it again for 24 hours.

**3. On a timeout, a 5xx or a 429, send it again**

Send the same body with the same key. After a `429`, wait the seconds in `Retry-After` first; after a `5xx` or a timeout, back off for a few seconds more each time, and keep the same key while the answer is `409` `idempotency_in_progress`. An answer that carries `Idempotent-Replayed: true` is the first call's: nothing ran twice. On `409` `idempotency_outcome_unknown`, stop retrying and check what was sent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.