Idempotency

A network timeout does not tell you whether the SMS was sent. To retry safely, send the Idempotency-Key header on POST /sms and POST /otp/send (UUID recommended, 255 characters max).

curl -X POST "https://api.labyrinthe-rdc.com/api/public/v1/sms" \
  -H "Authorization: Bearer lsk_test_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-1042-ready" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"243812345678","body":"Votre commande 1042 est prête."}'

Rules#

• A request replayed with the same key within 24 h returns the same response, with no new send or debit, and the Idempotent-Replayed: true header.
• The key is scoped to the API key and the operation: /sms and /otp/send have separate key spaces.
• It is bound to the normalized content: normalized, deduplicated recipients, body (after strip_accents), sender and reference for /sms; number, template, locale, web_otp_domain and strip_accents for /otp/send. 0812345678 then 243812345678 with the same key = replay.
• A failed request does not store the key: fix it and retry with the same key.

Conflicts#

• 409 IDEMPOTENCY_KEY_REUSED: same key, different content. Generate one key per business operation.
• 409 IDEMPOTENCY_REQUEST_IN_PROGRESS: the original request is still running (Retry-After: 5). Retrying with the same key is safe.
• 409 IDEMPOTENCY_KEY_UNRESOLVED: the original request failed unexpectedly, its outcome is unknown (an SMS may have been sent). Do not retry automatically: check (GET /sms?reference=), then resend with a new key.

Choosing the key#

Derive the key from the business event (order-1042-shipped, login-<session>) rather than a random UUID: a restart of your queue then replays the same key.

$client->sms->send(to: '243812345678', body: 'Votre commande est expédiée.', idempotencyKey: 'order-1042-shipped');