Idempotency

A network can fail after the server did the work but before you saw the answer. If you simply send the request again, a message could go out twice. The header Idempotency-Key prevents this.

#How to use it

Send a unique value for each operation, for example a UUID. Use the same value when you repeat that operation. This example creates a contact; calls that send messages use the header in the same way.

curl -X POST "https://api.smartchat.marketing/v1/contacts" \
  -H "Authorization: Bearer $SMARTCHAT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mia Muster", "phone": "+4915112345678"}'

The key has 1 to 255 visible ASCII characters.
It is required on every call that sends messages and on every call that creates something with an outside effect. The reference page of a call says "Required". Without it the answer is idempotency_key_required.
It is optional on some other calls, and it works if you send it.

#What happens on a repeat

You send	You get
The same key and the same request	The first answer again, with the header `Idempotent-Replayed: true`. Nothing is done twice.
The same key and a different request	422 `idempotency_key_reused`. Use a new key.
The same key while the first request still runs	409 `idempotency_in_progress` with `Retry-After`. Wait and repeat.

Keys are kept for 24 hours. They belong to your key and your account.

#What is not stored

Answers with 401, 403, 409, 429 and 503 are not stored. Nothing was done, or the state can change, so the key is free again.

Some 422 refusals depend on the state of your account. Nothing was sent, and the state can change (a template gets approved, a window opens, a contact confirms). These refusals are not stored either, so you can repeat the same request with the same key once the state has changed:

Other errors are stored, in particular errors that come from a service behind us (for example WhatsApp), because it is not clear if the message was sent. A repeat with the same key then gives the same answer and never a second send.

#Calls that take no key on purpose

create_webhook_endpoint and rotate_webhook_secret take no Idempotency-Key. Both answers contain a signing secret, and a secret is never kept in the replay storage. A repeated call therefore creates a second endpoint (the endpoint limit applies) or rotates the secret again. If you did not see the answer, list your endpoints first and unsubscribe the extra one (unsubscribe_webhook_endpoint) or reuse it.

#The key in MCP tools

The MCP tools take the same key as the argument idempotency_key. The rule is the same as in REST, with one help for agents:

The tool	Without a key
Sends a message	Refused with `idempotency_key_required`, as in REST. Send a key.
Creates something (for example a contact or a draft)	The server makes a key from the tool name and the arguments. It is valid for one minute. The same call within that minute returns the first answer. Send your own key to get the full 24 hours.
Changes something that already exists (set a status, add a tag)	No key is made. A repeat does the change again, because a change can be wanted twice.

#Required, optional, not needed

Every reference page shows exactly one of three words for the Idempotency-Key:

Word	Meaning
Required	Without the key the call answers `idempotency_key_required`.
Optional	The call works without it. If you send a key, a repeat returns the first answer.
Not needed	The call does not ask for a key.

The reference page also says in the row "Safe to repeat" whether a repeat is harmless by itself. This is a separate fact. A call that changes a setting or reads data can be repeated without a key because the end state is the same. A call that creates something or does work each time is not safe to repeat without a key.