Idempotency

A request that times out may or may not have happened. Retrying a POST blindly can make two links, two exports, two webhook endpoints. An Idempotency-Key makes the retry safe: send the same key with the same body, and you get the first answer back instead of a second action.

curl https://api.akteora.com/v1/brands/brd_01K59Y7T3HR2D6FBJ3M1Q0W8ZK/links \
  -H "Authorization: Bearer $AKTEORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d0c9f5e-8a41-4b43-9d8e-2a7f1c6b0e93" \
  -d '{ "title": "How was your first month?", "…": "…" }'

• Any POST accepts it. PATCH, PUT and DELETE are already safe to repeat.
• Use a new key for each thing you mean to do — a UUID is ideal — and the same key for every retry of it.
• Same key, same body: the stored response is returned, with its original status, and the header Idempotency-Replayed: true. Nothing happens a second time.
• Same key, different body: 409 idempotency_key_reused. Reusing a key for different content is a bug in the caller, and silently returning the first answer would hide it. The body is compared by content, not by key order or spacing.
• Same key while the first request is still running: 409 too. Retry after a moment.
• Keys last 24 hours. After that a key is forgotten and acts as new.
• Keys are per organisation, and test mode and live mode are separate organisations: the same key in each mode is two keys.
• Without the header, a request runs every time it is sent.

The SDK passes it like any header:

await unwrap(
  akteora.POST('/v1/exports', {
    body: { format: 'csv' },
    headers: { 'Idempotency-Key': crypto.randomUUID() },
  }),
)