Idempotency

How it works

Pass a unique key per logical send attempt:

curl -X POST https://api.robase.dev/v1/sms \
  -H "Authorization: Bearer rb_live_xxx" \
  -H "Idempotency-Key: order-92413-dispatch-sms" \
  -H "Content-Type: application/json" \
  -d '{"to":"+2348012345678","from":"SHUTTLERS","body":"Your ride arrives in 3 min."}'

await pm.sms.send(
  { to: '+2348012345678', from: 'SHUTTLERS', body: 'Your ride arrives in 3 min.' },
  `order-${orderId}-dispatch-sms`  // idempotency key
);

pm.sms.send(
    to="+2348012345678", from_="SHUTTLERS",
    body="Your ride arrives in 3 min.",
    idempotency_key=f"order-{order_id}-dispatch-sms",
)

pm.SMS.Send(ctx, &robase.SendSMSRequest{
    To: "+2348012345678", From: "SHUTTLERS", Body: "Your ride arrives in 3 min.",
}, robase.WithIdempotencyKey(fmt.Sprintf("order-%d-dispatch-sms", orderID)))

Replayed responses include an Idempotent-Replay: true header so you can tell them apart from fresh requests.

Rules

Keys are scoped to the project and the endpoint

order-92413-dispatch-sms on /v1/sms is distinct from the same key on /v1/emails. And keys from project A never collide with project B.

Keys live for 24 hours

After 24 hours the cached response is evicted. If you retry later than that, you get a fresh attempt — so keep retries inside a reasonable window.

Failures are retryable, not cached

We only cache 2xx and 4xx responses. 5xx errors are not cached — the retry with the same key triggers a fresh attempt.

Batch rows each need their own key

For POST /v1/sms/batch, put the per-row key on each element:

{
  "from": "SHUTTLERS",
  "messages": [
    { "to": "+2348012345678", "body": "...", "idempotency_key": "order-1-sms" },
    { "to": "+2348087654321", "body": "...", "idempotency_key": "order-2-sms" }
  ]
}

Per-row keys are namespaced separately from the top-level Idempotency-Key header.

What to use as a key

A good idempotency key is derived from your data, not random:

order-92413-dispatch-sms ✅

user-42-password-reset-2026-04-17 ✅

uuid.v4() ❌ (a fresh UUID per retry is not idempotent — you’ll send twice)

If your natural key isn’t unique per send attempt, compose it: user-42-reset-${Date.now()} bucketed to the minute.

Get Started

SMS

Email

Tutorials

SDKs

How it works

Rules

What to use as a key

​How it works

​Rules

​What to use as a key

How it works

Rules

What to use as a key