Idempotency & retries

Which calls are safe to retry, and how to avoid duplicate sends.

Some API calls are safe to repeat and some aren't. This page covers which is which, and how to avoid sending the same text twice when you're not sure a send went through.

The short version

Retry reads and upserts freely; retry message sends only after checking whether the first attempt went through.


Which calls are safe to retry?

Safe to retry

CallWhy
Any GETReads have no side effects.
POST /v1/contacts, POST /v1/contacts/batchUpserts keyed by phone number. Running twice produces the same state.
POST /v1/contact-groups/{id}/contacts, DELETE …/contactsAdding a contact that's already in the group is a no-op; same for removal.
POST /v1/blocksBlocking an already-blocked number is a no-op.
PUT anythingSame input, same result. (Keyword settings PUT is a partial update: fields you omit are left unchanged.)
DELETE /v1/messagesDeleting the same ID again, or an ID that doesn't exist, returns 200 {}. An ID that belongs to a different account returns 401.
DELETE …/{id} (contacts and similar)A second delete returns 404, which you can treat as success.

Retry with care

These create something new or rotate credentials, so check before you retry.

CallWhy
POST /v1/tokens/create, /refreshEach call issues a new pair and the refresh invalidates the old refresh token. Retry, but store whatever comes back last.
POST /v1/message-templates, POST /v1/media-files, POST /v1/contact-groupsA retry creates a second template/file/group. Check for an existing one by name before creating.
POST /v1/webhooks/subscriptionsSame: you'd end up with two subscriptions and two callbacks per event.

Don't retry blindly

POST /v1/messages. A retry is a second message to real people. If a send returns a 5xx, or the connection drops before you get a response, the message may already have been accepted. Before sending again, check whether it went out: look for it with GET /v1/messages, filtered to outbound messages (filters[incoming][eq]=false), the recipient (filters[contactNumber][eq]), and a recent filters[sentAt][gte]. Compare the sender, recipient, message text, and time before deciding it's yours. Identical sends close together can still be ambiguous; if the lookup doesn't settle it, leave the send unresolved for a person to review rather than sending again.

Two habits prevent most duplicates:

  • Save the send's id as soon as you get the 201.
  • Make sure each event that triggers a text (an order shipping, a booking) sends only once, even if your system processes it twice.

Related


Did this page help you?