Skip to Content
API keys are issued to organizations with a signed BAA. Request API access →
Idempotency

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-1d2e3f4a5b6c

How it works

You sendBloomText returns
A new keyProcesses the request normally and remembers the result for 24 hours.
The same key, method, path, and body within 24 hoursThe original response, without running the write again.
The same key with a different method, path, or body409 Conflict with code: idempotency_key_reused.
The same key while the first request is still running409 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

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