Glossary
Idempotency
Idempotency is the property of an operation where performing it multiple times produces exactly the same result as performing it once, making distributed systems safe to retry without creating duplicate effects.
General definition
Idempotency is critical in any network-connected system because networks are unreliable. When a client sends a request and receives no response (due to a timeout, connection drop or client crash), it cannot know whether the server processed the request. Without idempotency, retrying may cause duplicate records, double charges or duplicate messages. With idempotency, retrying is always safe.
- HTTP GET, HEAD and DELETE are naturally idempotent: calling them multiple times has the same effect
- HTTP POST is not naturally idempotent, but an idempotency key (a unique client-generated ID sent with the request) makes it so: the server stores the key and returns the cached result on duplicate requests
- HTTP PUT is idempotent if it replaces a resource rather than partially updating it
In messaging systems, idempotency prevents the classic “duplicate message” bug where a retry of a failed send results in the recipient seeing the same message twice. The client generates a unique message ID (often a UUID or a timestamp-plus-random string) and includes it in the send request. The server indexes by this ID and deduplications any retry that arrives within a configured window.
Idempotency is distinct from rate limiting (which throttles excessive requests) and from webhook delivery guarantees (where the consumer must handle potential duplicate deliveries using the same principle).
In the Ethora ecosystem
Ethora’s messaging API accepts a client-generated message ID on send operations. If a client retries after a network failure, the server recognises the duplicate ID and returns the original response without creating a second message. This ensures that mobile users on unreliable connections never see duplicated messages in a channel.
For integrations built on the AI SDK, idempotency keys also protect bot message delivery: if a webhook trigger fires twice (a common occurrence with at-least-once delivery systems), the SDK’s deduplication layer ensures the bot responds exactly once. This is especially important in regulated contexts where a duplicate clinical or financial alert could cause genuine operational confusion.
