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.
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
| Call | Why |
|---|---|
Any GET | Reads have no side effects. |
POST /v1/contacts, POST /v1/contacts/batch | Upserts keyed by phone number. Running twice produces the same state. |
POST /v1/contact-groups/{id}/contacts, DELETE …/contacts | Adding a contact that's already in the group is a no-op; same for removal. |
POST /v1/blocks | Blocking an already-blocked number is a no-op. |
PUT anything | Same input, same result. (Keyword settings PUT is a partial update: fields you omit are left unchanged.) |
DELETE /v1/messages | Deleting 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.
| Call | Why |
|---|---|
POST /v1/tokens/create, /refresh | Each 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-groups | A retry creates a second template/file/group. Check for an existing one by name before creating. |
POST /v1/webhooks/subscriptions | Same: 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
idas soon as you get the201. - Make sure each event that triggers a text (an order shipping, a booking) sends only once, even if your system processes it twice.
Related
- Errors — the retry policy for
429and5xx - Rate limits
- Webhooks
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated about 19 hours ago