Idempotency

All write endpoints (POST, PATCH) require an Idempotency-Key header. This prevents duplicate operations if a request is retried after a timeout or network failure.

Idempotency-Key: <your-unique-key>

Key format

A key is 1 to 255 printable ASCII characters (0x21-0x7E). Letters, digits, and punctuation such as -, _, ., and : are all allowed, so a key like order-123:create-post:v1 is fine. Spaces, tabs, control characters, and non-ASCII characters are not. Leading and trailing whitespace is trimmed.

A key outside this format returns 400 PUBLIC_API_IDEMPOTENCY_KEY_INVALID and nothing is created.

How it works

1. First request with a key is executed normally.
2. If you resend the same key with the same payload, the API returns the original response without re-executing the operation.
3. If you resend the same key with a different payload, the API returns 409 PUBLIC_API_IDEMPOTENCY_CONFLICT.

Idempotency keys are scoped to your API key and expire after 24 hours.

Key generation

Use a key that is stable for a given logical operation but unique across distinct operations. Good strategies:

# Date-based for scheduled jobs
post-linkedin-2026-02-17-campaign-spring

# UUID per logical write
$(uuidgen)

# Hash of operation parameters
echo -n "workspace:${WORKSPACE_ID}:post:${DATE}:${PLATFORM}" | sha256sum

Retry pattern

IDEM_KEY="post-create-$(date +%Y%m%d)-001"

# Retry the same request with the same key
for i in 1 2 3; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "$AIDELLY_API_BASE/posts" \
    -H "Authorization: Bearer $AIDELLY_API_KEY" \
    -H "Idempotency-Key: $IDEM_KEY" \
    -H "x-aidelly-workspace-id: $WORKSPACE_ID" \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD")
  [[ "$STATUS" == "200" ]] && break
  sleep $((i * 2))
done

MCP tool calls

When Aidelly tools are called via MCP, the MCP server auto-generates an Idempotency-Key for write operations if you don't provide one. This means repeated MCP tool calls for the same logical action are still idempotent by default.

Error codes