Skip to content

Idempotency

A network can fail after the API has accepted your request but before you see the answer. If you retry blindly, the customer gets the SMS twice. Send an Idempotency-Key header and SMSFabric runs the request once, then replays the stored response for every retry with the same key.

  1. You send a create request with Idempotency-Key: <your key>.
  2. SMSFabric claims the key for your organization and runs the request.
  3. On success, the response (status and body) is stored, encrypted, for 24 hours.
  4. A retry with the same key and the same request gets that stored response back, with the header Idempotent-Replayed: true. Nothing runs again.

A request that fails (any 4xx or 5xx) does not use up the key, so you can fix the request and send it again with the same key.

Keys are scoped to your organization: two organizations can use the same key without conflict.

Every POST that creates something:

Endpoint Creates
POST /v1/messages Messages
POST /v1/verifications A verification (one-time code)
POST /v1/contacts A contact
POST /v1/contact-groups A contact group
POST /v1/templates A template
POST /v1/campaigns A draft campaign
POST /v1/blacklist A blacklist entry
POST /v1/webhooks A webhook endpoint
POST /v1/devices/pairing-tokens A pairing token
POST /v1/pools A device pool
POST /v1/api-keys An API key (signed-in users only)
POST /v1/org/invitations A team invitation (signed-in users only)

Other endpoints ignore the header. PATCH, PUT and DELETE requests are naturally safe to repeat.

  • 1 to 255 characters from A–Z a–z 0–9 _ - : .. Anything else returns 400 invalid_idempotency_key.
  • Derive it from your own data when you can: order-1042-shipped, signup:usr_8812:otp. Then a retry from a different worker or after a restart uses the same key.
  • Otherwise generate a UUID once per logical operation and keep it with the job, not per HTTP attempt.
Terminal window
# Run this twice: the second call returns the same message ids
# and the header "Idempotent-Replayed: true".
curl -i https://api.smsfabric.com/v1/messages \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: invoice-7781-reminder" \
-d '{"to": "+201001234567", "body": "Invoice 7781 is due on 1 December."}'
Status code Meaning What to do
400 invalid_idempotency_key The key is empty, too long or has other characters. Use 1 to 255 characters of A–Z a–z 0–9 _ - : ..
409 idempotency_in_progress The first request with this key is still running. Wait a second and retry with the same key.
422 idempotency_key_reused The key was used in the last 24 hours with a different method, path or body. Use a new key for a new operation. Never reuse a key for different content.