# Safe retries

> Send a request again after a timeout without calling anybody twice.

Networks fail in the middle of requests. When you did not get an answer you cannot tell whether the
call was placed — so send your own id for it, and send it again with the same id.

## The Idempotency-Key header

| Request | The header |
|---|---|
| Place a call | Required. Without it: `400 idempotency_key_required`. |
| Start a chat | Optional. The same request again returns the same chat. |
| Send a chat message | Optional. The same message again returns the same reply, without asking the agent twice. |

Up to 120 characters. **Build it from your own data** — `lead-8812-attempt-2`, not a random string
made fresh for each try — so a retry after a crash still carries the same id.

The SDKs make a key for each call and send the same one on each of their own retries. Give your own
through their idempotency key option, or as the `Idempotency-Key` header itself: either way, yours
is the one sent.

## What happens

| Situation | Result |
|---|---|
| Same key, same request | The same conversation as it is now, with the header `Idempotent-Replayed: true`. |
| Same key, a different request | `422 idempotency_key_reused`: the agent, the numbers, the values and the metadata are compared. |
| Same key, two requests at the same moment | One of them places the call; the other gets that call. |
| The call failed after it was saved | A retry returns that failed conversation and never calls again. To call again, use a new key. |

A key belongs to its conversation for as long as the conversation exists — reusing last week's key
returns last week's call. A test key's ids and a live key's never meet.

## Ending

Ending a conversation is always safe to send again: ending one that has already ended returns it.