Start Here

Idempotency

An Idempotency-Key makes a request safe to retry. Send the same key twice and the second request returns the first result instead of doing the work again.

Why it matters

Situation: you send a broadcast to 10,000 numbers and the connection drops before the response arrives. Did it go out? Without a key, retrying might message all 10,000 people twice. With a key, the retry simply hands back the broadcast that was already created.

Sending a key

Add an Idempotency-Key header to POST /v1/otp/send or POST /v1/broadcast — the two routes that spend money. Use any string up to 255 characters that identifies the action on your side, such as an order id or a UUID you store with it.

curl -X POST https://api.transmitinfra.com/v1/broadcast \
  -H "Authorization: Bearer $TRANSMIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: statement-run-2026-09" \
  -d '{
    "message": "Your September statement is ready.",
    "recipients": [
      "+220833001234",
      "+220877005678"
    ]
  }'

How keys behave

Replayed for 24 hours: The first successful response is stored for 24 hours. A repeat returns the same status and body with an Idempotent-Replay: true header — no second code, no second broadcast.
Bound to one request: A key remembers the route and body it first arrived with. Reusing it with a different body or on a different route answers 409 CONFLICT.
One at a time: A repeat while the first request is still running answers 409 IDEMPOTENCY_CONFLICT with Retry-After: 2. Wait and retry with the same key.
Failures are not stored: Only 2xx responses are remembered. A request that failed frees its key immediately, so you can retry it.
Scoped to your workspace: Two workspaces can use the same string without colliding.
Fails safe: If we cannot check the key, the request is refused with 503 SERVICE_UNAVAILABLE and nothing is sent. Retry with the same key.

A keyed broadcast is also recorded in our database next to the broadcast itself, so a retry inside the 24 hours can never send the list twice — even if the stored response were lost.

Broadcasts without a key

Broadcasts sent without a key get a lighter guard: the same channel, message, schedule and recipient list (in the same order) from the same workspace within 60 seconds returns the first broadcast instead of creating another. It catches a double-clicked send button, not a retry an hour later — use a key for that.