Idempotency
Networks fail. A request can time out after BloomText has already sent your message. Idempotency keys let you retry any write without sending it twice.
Every POST request requires an Idempotency-Key header. Generate a new UUID for each logical write, and reuse the same key when you retry that write.
Header
Idempotency-Key: 9f1c2b3a-7d4e-4f5a-8b6c-1d2e3f4a5b6cHow it works
| You send | BloomText returns |
|---|---|
| A new key | Processes the request normally and remembers the result for 24 hours. |
| The same key, method, path, and body within 24 hours | The original response, without running the write again. |
| The same key with a different method, path, or body | 409 Conflict with code: idempotency_key_reused. |
| The same key while the first request is still running | 409 Conflict with code: idempotency_request_in_progress. Retry shortly. |
DELETE requests are identified by their path, so they don’t take a key. Deleting something twice returns 404 the second time, which you can treat as success.
Retry safely
JavaScript
send-with-retry.mjs
async function sendMessage(conversationId, body) {
const idempotencyKey = crypto.randomUUID() // one key per logical send
for (let attempt = 1; attempt <= 4; attempt++) {
try {
const response = await fetch(`https://api.bloomtext.com/v1/conversations/${conversationId}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
'Idempotency-Key': idempotencyKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({ body }),
})
if (response.status < 500 && response.status !== 429) return await response.json()
} catch {
// Network error: safe to retry with the same key.
}
await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250))
}
throw new Error('Message not sent after 4 attempts')
}Choosing keys
- Generate the key once per logical action, before the first attempt, and keep it with the job. For a reminder job, derive it from something stable like the appointment ID and send date, so a rerun of the whole job can’t double-send.
- Never reuse a key for a different message. You’ll get
409 idempotency_key_reused. - Keys are scoped to your organization. Other organizations’ keys never collide with yours.
Last updated on