Idempotency

Networks fail. If your request to POST /v1/sms/send times out, you can't tell whether the SMS went out. Retrying blindly could send it twice — and charge you twice.

Add an Idempotency-Key header and retries become safe:

curl -X POST https://api.cloudmetis.com/v1/sms/send \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to": "+254712345678", "message": "Your order #1042 has shipped."}'

How it works

You send the same key…	Result
…with the same body within 24 hours	The original response is returned, with the header Idempotent-Replayed: true. Nothing is sent again.
…with a different body	409 idempotency_conflict
…while the first request is still processing	409 idempotency_conflict — retry shortly
…after 24 hours	Treated as a new request

If the first request failed before anything was sent (for example send_failed), the key is released and you can retry with the same key.

A replayed response is identical to the original, including the status code (201 or 202) and the message_id/batch_id.

Choosing keys

• Use something that identifies the business event, not the attempt: order-1042-shipped, otp-7f3a…, promo-2026-11-01.
• Keys are per API key, up to 255 printable ASCII characters, no spaces.
• "Same body" means the same JSON fields and values in the same order — build the body the same way on every retry.

Example

POST /v1/sms/send   Idempotency-Key: order-1042-shipped   → 201  msg_184
POST /v1/sms/send   Idempotency-Key: order-1042-shipped   → 201  msg_184  (Idempotent-Replayed: true)
POST /v1/sms/send   Idempotency-Key: order-1042-shipped   (different message) → 409 idempotency_conflict