Idempotency-Key header solves this: send the same key with the same request, and OnlyX performs it at most once.
How to use it
-
Format: 8 to 64 characters from
A-Z,a-z,0-9,-and_. A UUID is ideal. -
Accepted on every
POST,PUT,PATCHandDELETEunder/v1. -
Required on:
POST /v1/conversations/{conversationId}/messages(sending a message)POST /v1/creators(adding a creator)POST /v1/creators/{creatorId}/tracking-links(creating a tracking link)
400 IDEMPOTENCY_KEY_REQUIRED. - Recommended on every other write that reaches fans: releasing a chat, turning a chat’s AI on, turning a creator’s AI on, resolving a hand-off, changing AI settings, replacing the welcome message.
What happens on a retry
“The same request” means the same method, the same path and the same JSON body. Key order and whitespace in the body do not matter.
For sends, the key also travels with the message all the way to delivery, so even a retry that raced the original cannot deliver the message twice.
Rules of thumb
- One key per intended action. Generate the key when you decide to do something (for example when a draft is approved), store it with that action, and use it for every attempt.
- Never generate a new key for a retry. A new key means a new action: that is how double sends happen.
- Keys are unique per workspace, across all your API keys and connected apps. Use random UUIDs, not counters or timestamps that two integrations could produce at the same time.
- Replays last 24 hours. After that, the same key is treated as new. Do not retry a write more than a day later expecting protection.
- Fix, then use a new key. If the first attempt failed with
400 VALIDATION_ERROR, the corrected request is a different action: give it a new key. (Reusing the old key would also work, because a failed attempt releases its key, but a new key keeps your logs honest.) - Idempotency is not delivery. A send that returned
202and later showsdelivery.status: "unconfirmed"must not be sent again with a new key. The fan almost certainly has it.
Example: a safe send with retries
Related
- Read and send messages: delivery states after a send.
- Errors: which errors are safe to retry.