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.
How it works
Section titled “How it works”- You send a create request with
Idempotency-Key: <your key>. - SMSFabric claims the key for your organization and runs the request.
- On success, the response (status and body) is stored, encrypted, for 24 hours.
- 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.
Which endpoints accept it
Section titled “Which endpoints accept it”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.
Choose a key
Section titled “Choose a key”- 1 to 255 characters from
A–Z a–z 0–9 _ - : .. Anything else returns400 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.
Retry safely
Section titled “Retry safely”# 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."}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
// The SDK retries network errors, 429 and 5xx on its own (2 retries by default)// and reuses this key for every attempt. Without a key it generates a UUID per call.const messages = await sf.messages.send( { to: '+201001234567', body: 'Invoice 7781 is due on 1 December.' }, { idempotencyKey: 'invoice-7781-reminder' },);console.log(messages[0].id);import osimport timeimport requests
def send_once(payload: dict, key: str) -> dict: headers = {"X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": key} for attempt in range(4): try: res = requests.post("https://api.smsfabric.com/v1/messages", json=payload, headers=headers, timeout=30) except requests.RequestException: time.sleep(2 ** attempt) continue if res.status_code == 409 or res.status_code == 429 or res.status_code >= 500: time.sleep(int(res.headers.get("Retry-After", 2 ** attempt))) continue res.raise_for_status() return res.json() raise RuntimeError("gave up after 4 attempts")
send_once({"to": "+201001234567", "body": "Invoice 7781 is due on 1 December."}, "invoice-7781-reminder")<?phpfunction sendOnce(array $payload, string $key): array { for ($attempt = 0; $attempt < 4; $attempt++) { $ch = curl_init('https://api.smsfabric.com/v1/messages'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: ' . $key, ], CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE); if ($body !== false && $status < 300) { return json_decode($body, true); } if ($body !== false && $status < 500 && $status !== 409 && $status !== 429) { throw new RuntimeException("SMSFabric error $status: $body"); } sleep(2 ** $attempt); } throw new RuntimeException('Gave up after 4 attempts');}
sendOnce(['to' => '+201001234567', 'body' => 'Invoice 7781 is due on 1 December.'], 'invoice-7781-reminder');Errors
Section titled “Errors”| 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. |