Using the API well

Idempotency and safe retries

Networks fail. An Idempotency-Key lets you retry any write without the risk of sending the same WhatsApp message twice.

How it works

Every POST, PUT and PATCH requires an Idempotency-Key header: any unique string of up to 255 printable characters (a UUID is ideal). ShipMsg remembers each key for 24 hours, per account and environment.

curl

KEY=$(uuidgen)   # generate once per logical action, reuse on every retry of it
curl -X POST "https://api.shipmsg.com/v1/accounts/$SHIPMESSAGES_ACCOUNT_SID/messages" \
  -H "Authorization: Bearer $SHIPMESSAGES_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"from": "WA…", "to": "+15550000001", "type": "text", "text": {"body": "Hi"}}'

You send the same key…	ShipMsg answers
with the same request, after the first one finished	The first response again, with the header `Idempotent-Replayed: true`. Nothing is sent twice.
while the first one is still running	`409` IDEMPOTENCY_IN_PROGRESS — wait a moment and retry.
with a different body or endpoint	`409` IDEMPOTENCY_KEY_REUSED — a key names one action.

When to retry

Network errors and timeouts: retry with the same key.
Errors with "retryable": true (429, some 5xx): wait retryAfterSeconds, then retry with the same key.
Everything else: fix the cause first; retrying the same request will fail the same way.
Back off exponentially (1 s, 2 s, 4 s …) and give up after a few attempts.

The SDKs generate a key for every write and follow these rules for you. Read and delete requests (GET, DELETE) are safe to repeat and take no key.