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
- Retry: A retry is trying the same thing again after it failed, usually after a short wait, in case the problem was only temporary.
- Rate limit: A rate limit is a cap on how much can be done in a set time, such as messages in a day, which keeps a service fair and an account safe.
- Webhook signature: A webhook signature is a stamp added to each message a service sends to your web address, so you can check it really came from them and was not changed on the way.
- AI agent: An AI agent is an AI model, such as ChatGPT, Claude or Grok, that can take actions with tools you give it, like reading a message and sending a reply, rather than only chatting.
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.