Idempotency - Comms

Outbound message creates accept an idempotency key. Replaying the same key returns the original result instead of placing a second message on the line.

Why it matters

Your infrastructure will retry:

HTTP timeouts after Comms already accepted the send
Queue redelivery
Deploy mid-request
Manual “run again” on a failed job

Without idempotency, customers get duplicate texts. With it, retries are free.

How to send the key

Either header or body (header preferred):

Idempotency-Key: order-4242-shipped

{
  "to": "+12125550147",
  "body": "Your order shipped.",
  "idempotency_key": "order-4242-shipped"
}

Choosing a key

Good	Why
`order-{id}-shipped`	Stable per business event
`booking-{id}-reminder-t24`	Distinct from other reminders
UUID generated once and stored on the job row	Safe if you persist it before POST

Avoid	Why
`Date.now()` only	Every retry is a new key
Random UUID recreated on each attempt	Same problem
User-visible content of the body	Collisions and encoding noise

Responses

Status	Meaning
202	First acceptance — delivery will proceed
200 + `"duplicate": true`	Same key already processed — use returned `message`

Both should count as success in your application.

Scope

Idempotency applies to outbound sends (POST /api/v1/comms/messages). List endpoints are read-only and do not need a key.

​Why it matters

​How to send the key

​Choosing a key

​Responses

​Scope

Why it matters

How to send the key

Choosing a key

Responses

Scope