Idempotency Key

An idempotency key is a unique value a client sends with a request so that retrying the request does not perform the action twice. Payment APIs popularized it: Stripe accepts an idempotency key so a network error never charges a card twice. 1 The IETF is standardizing it as the Idempotency-Key HTTP header. 2

The problem it solves

You send a request to publish a post. The connection drops before the answer arrives. Did it work? Without an idempotency key, the safe-looking retry can publish the same post twice. With a key, the server recognizes the retry and returns the original result.

How to use one

1. Create a new random key (for example a UUID) for each action, such as “publish this post”.
2. Send it in the Idempotency-Key header.
3. If you need to retry, send the exact same request with the same key.
4. Never reuse a key for a different action.

Why it matters for AI agents

Autonomous agents retry on their own when a tool call times out. Without idempotency, an agent that retries after a slow response can post the same update twice. With it, retries are harmless.

Idempotency keys in Publora

The create-post endpoint of the Publora API accepts an optional Idempotency-Key header. The same key with the same body replays the original response, including the same post ID, so no second post is created. The same key with a different body returns 422 IDEMPOTENCY_KEY_CONFLICT, and a retry while the first request is still running returns 409 IDEMPOTENCY_IN_FLIGHT. 3