Idempotency

An idempotency key lets you retry a write without performing it twice. If a request times out after BloomText has already sent your message, the retry returns the original result instead of sending again.

Every POST request requires an Idempotency-Key header. Generate a new UUID for each logical write, and reuse it when you retry that write.

Header


Idempotency-Key: 9f1c2b3a-7d4e-4f5a-8b6c-1d2e3f4a5b6c

Every retry must reuse its Idempotency-Key. A new key is a new message. If your integration sends a retry with a freshly generated key, BloomText treats it as a separate request and texts the patient again. That duplicate is a bug in the integration, and BloomText can’t detect it. Store the key with the job before the first attempt, and send the same key on every retry, including after timeouts, 429, and 5xx responses.

How 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. It carries `Idempotent-Replayed: true` and the original request’s `X-Request-Id`, so it matches what you logged the first time.
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.

PATCH requests set fields to the values you send, so repeating one is safe and they don’t take a key. DELETE requests are identified by their path, so they don’t take a key either. A second delete of the same resource returns 404, which you can treat as success.

Retry safely

JavaScript

send-with-retry.mjs


async function sendMessage(patientId, 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/patient-messages', {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.BLOOMTEXT_API_KEY}`,
          'Idempotency-Key': idempotencyKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ to: { patient_id: patientId }, body, channel: 'sms' }),
      })
      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')
}

Python

send_with_retry.py


import os
import time
import uuid
 
import requests
 
 
def send_message(patient_id: str, body: str) -> dict:
    idempotency_key = str(uuid.uuid4())  # one key per logical send
 
    for attempt in range(1, 5):
        try:
            response = requests.post(
                "https://api.bloomtext.com/v1/patient-messages",
                headers={
                    "Authorization": f"Bearer {os.environ['BLOOMTEXT_API_KEY']}",
                    "Idempotency-Key": idempotency_key,
                },
                json={"to": {"patient_id": patient_id}, "body": body, "channel": "sms"},
                timeout=10,
            )
            if response.status_code < 500 and response.status_code != 429:
                return response.json()
        except requests.RequestException:
            pass  # Network error: safe to retry with the same key.
        time.sleep(2**attempt * 0.25)
    raise RuntimeError("Message not sent after 4 attempts")

Go

retry.go


func sendMessage(patientID, text string) (*http.Response, error) {
	idempotencyKey := uuid.NewString() // one key per logical send
	payload, _ := json.Marshal(map[string]any{
		"to":      map[string]string{"patient_id": patientID},
		"body":    text,
		"channel": "sms",
	})
	url := "https://api.bloomtext.com/v1/patient-messages"
 
	for attempt := 1; attempt <= 4; attempt++ {
		req, _ := http.NewRequest("POST", url, bytes.NewReader(payload))
		req.Header.Set("Authorization", "Bearer "+os.Getenv("BLOOMTEXT_API_KEY"))
		req.Header.Set("Idempotency-Key", idempotencyKey)
		req.Header.Set("Content-Type", "application/json")
 
		res, err := http.DefaultClient.Do(req)
		if err == nil && res.StatusCode < 500 && res.StatusCode != 429 {
			return res, nil
		}
		if err == nil {
			res.Body.Close()
		}
		time.Sleep(time.Duration(1<<attempt) * 250 * time.Millisecond)
	}
	return nil, errors.New("message not sent after 4 attempts")
}

Ruby

send_with_retry.rb


require "net/http"
require "json"
require "securerandom"
 
def send_message(patient_id, body)
  idempotency_key = SecureRandom.uuid # one key per logical send
  uri = URI("https://api.bloomtext.com/v1/patient-messages")
 
  4.times do |attempt|
    begin
      request = Net::HTTP::Post.new(uri)
      request["Authorization"] = "Bearer #{ENV.fetch("BLOOMTEXT_API_KEY")}"
      request["Idempotency-Key"] = idempotency_key
      request["Content-Type"] = "application/json"
      request.body = { to: { patient_id: patient_id }, body: body, channel: "sms" }.to_json
 
      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
      code = response.code.to_i
      return JSON.parse(response.body) if code < 500 && code != 429
    rescue StandardError
      # Network error: safe to retry with the same key.
    end
    sleep(2**(attempt + 1) * 0.25)
  end
  raise "Message not sent after 4 attempts"
end

Choose keys

Generate the key once per logical action, before the first attempt, and keep it with the job. Derive it from something stable, like a UUIDv5 of the draft or appointment ID, so a double click or a rerun of the job can’t send twice.
Reuse the key on every retry of that action, whatever the failure was: a timeout, a dropped connection, 429, or 5xx. Never generate a new key to retry. A new key is a new message.
Use a new key for each different message. Reusing one returns 409 idempotency_key_reused.
Keys are scoped to the credential. The same key sent with two different API keys counts as two separate writes.