Idempotency - Kavenio

Idempotency prevents a retried mutation from creating the same resource or provider side effect twice. Support is endpoint-specific. Use the header named by the endpoint reference and reuse its value only for retries of the same logical request.

Creating posts

POST /v1/posts uses X-Request-Id for request replay protection. Kavenio scopes the key to the authenticated subject and organization, hashes the canonical request body, and keeps the completed result for five minutes.

curl --request POST "https://api.kavenio.com/v1/posts" \
  --header "Authorization: Bearer $KAVENIO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-Request-Id: post_20260716_launch_01" \
  --data '{
    "profileId": "aaaaaaaaaaaaaaaa",
    "isDraft": true,
    "content": "Release notes"
  }'

Within the five-minute window:

the same request ID and the same body return the same post; if publishing is still progressing, the response can contain the post’s newer state;
the same request ID with a different body returns VALIDATION_ERROR;
a matching request that is still in progress returns CONFLICT;
keys are limited to 255 characters.

The JavaScript SDK generates a request ID for each posts.create() call. When your own retry wrapper may repeat a call, generate the ID once and pass the same value to every attempt:

const requestId = crypto.randomUUID();

const post = await retryTransiently(() =>
  client.posts.create(payload, { requestId }),
);

Generating a new ID inside the retry callback creates a new logical request and does not provide replay protection.

Other mutation endpoints

Some provider-backed mutation endpoints use Idempotency-Key instead. When an endpoint requires that header, send a unique value for the first attempt and reuse it for retries of the same request body. Do not reuse a completed key for a different operation.

Provider publishing is a separate boundary

API request idempotency prevents duplicate Kavenio resources. It does not prove that every provider accepts an idempotency key for the final publish call. Kavenio uses provider-native publish idempotency where the adapter and provider support it. When a non-idempotent provider may have accepted a publish but the result is missing, Kavenio marks the target action_required instead of blindly publishing it again. Inspect the target state and reconcile an unknown provider outcome before retrying.

​Creating posts

​Other mutation endpoints

​Provider publishing is a separate boundary

Creating posts

Other mutation endpoints

Provider publishing is a separate boundary