Idempotency

Idempotency-Key is accepted on write endpoints that support it to make retries safe.

If you call the same endpoint again with the same idempotency key (for the same project), Rooaak will return the original result rather than creating a duplicate.

Current key validation (src/lib/v1/idempotency.ts):

• trimmed non-empty string
• min length 4
• max length 200

For messaging, key collisions reuse existing message row and avoid duplicate writes.

When to use it

Use idempotency keys whenever your infrastructure might retry requests (timeouts, upstream retries, client reconnects).

At minimum:

• POST /v1/agents/:id/messages

What to put in the key

Choose a value that uniquely identifies the logical message in your system and is stable across retries.

Good examples:

• chat:${conversationId}:${messageId}
• slack:${teamId}:${eventId}
• whatsapp:${phoneNumberId}:${wamid}

Avoid:

• raw timestamps alone (can create duplicates on retry)