Spaces

What is a safe to retry?

Something is safe to retry, or idempotent, when doing it twice has the same result as doing it once, so a repeat never sends a second copy.

Also called: Idempotency, Idempotency key.

In plain words

A lift button is a good example. Press the call button once or five times and you still get one lift. Pressing again does no harm. That is what safe to retry means.

It matters for messages. Networks drop out, and an agent may not know whether a send worked. If it tries again and the system treats the repeat as new, your customer gets two identical messages. That looks careless.

The fix is a label. Each send carries a unique label, called an idempotency key. If the same label arrives twice, the service sees it is the same request and does not do it again. It simply hands back the first answer.

Your agent handles the labels for you. As an owner, the thing to know is that the agent can safely try again after a hiccup, so you will not see double messages.

It is the same reason a card machine says do not press pay twice. One charge is the goal, however many times a nervous finger taps.

How it works in Spaces

Sends need an idempotency key, sent as the Idempotency-Key header on REST (8 to 128 letters, digits, dots, dashes or colons) and as idempotency_key in MCP tools such as reply_in_chat and start_chat.

After a 429, retry with the same key. A held write waiting for approval returns the same approval when the same key is used. A repeated webhook delivery carries the same event id.

Related terms

FAQ

Do I need to make these labels myself?

No. Your AI agent or the software your developer builds adds them.

What happens if the same key is used twice?

Spaces treats it as one request and does not send a second copy.

Are the keys the same as API keys?

No. An API key identifies who is asking. An idempotency key labels one single send.

Is a webhook delivery safe to repeat?

Yes. A repeated delivery of the same event has the same event id and is not a second message.

Useful next: API reference, Sending limits, Errors explained. Every term: the glossary.