Retry an SMS send only when the failure is temporary: a timeout, a 5xx, or a rate limit. Stop and park the message when the failure is permanent, such as an opted-out number, an invalid number or a blocked send. Retrying a permanent failure never works and can cost you money or standing with carriers.
This post gives you a decision table, a retry shape, and a plan for the messages that fail for good. It assumes you already know why idempotency keys matter, so it covers that only briefly and spends its time on the rest.
Sort failures into three buckets
Every failed send falls into one of three buckets, and each gets different handling. Getting the bucket right is most of the work.
| Bucket | Examples | What to do |
|---|---|---|
| Temporary | Timeout, connection reset, 5xx, rate limit | Retry with backoff, same idempotency key |
| Permanent for this message | Invalid number, opted-out contact, banned number, landline refused | Don't retry. Record the reason and stop |
| Held, not failed | Quiet hours refusal (409 QUIET_HOURS_BLOCK) | Retry later, once the window opens |
The third bucket trips people up. A quiet-hours refusal isn't an error in your code or the number. It's a rule about time. A text you type in the dashboard or inbox to one person is scheduled for the recipient's next allowed time and sends itself (Cancel is in the thread). An API text is held only if the window opens within 6 hours. Otherwise it isn't sent, the API answers 409 QUIET_HOURS_BLOCK, and the sender sends it again once the window opens. Treat that as a scheduled retry, not a failure. The rate limits post covers the rate-limit side in more depth.
For the exact error codes your integration will meet, the Ready error docs are the source. Don't hard-code a list from memory. Map codes to buckets in one place so you can update it in one edit.
Retry with backoff and jitter
A good retry waits longer each time and adds randomness, so a thousand failed jobs don't all retry in the same second. The usual shape is a short first wait, a doubling delay, a cap, and a small attempt limit.
- Attempts: three to five is plenty for a text. A message that fails five times in a row needs a person or a different path, not a sixth try.
- Delay: start near a second, double each time, and cap the wait at something like a minute.
- Jitter: add a random fraction of the delay so retries spread out.
- Respect the server: if a response tells you how long to wait, wait that long.
Time matters for texts in a way it doesn't for most API calls. A "your code is 482913" message that arrives 20 minutes late is worse than none. Give each message a deadline, and drop it to the failure path when the deadline passes. A shipping notice can wait an hour. A login code can't.
The one rule about duplicates
Create the idempotency key when the job is created, store it with the job, and reuse it on every retry. Send it in the Idempotency-Key header, where any UUID works. A retried request with the same key, within the 7 days Ready keeps it, returns the first answer on Ready instead of sending again.
The failure that makes this necessary is the lost response. Your request reached the API and the text went out, but the answer never came back, so your code sees a timeout and retries. Without a key you'd text the customer twice. With one you won't. The full walkthrough, including the mistake of generating a new key on each attempt, is in our idempotency post. Don't build retry logic without it.
Build a dead-letter queue for messages that fail for good
A dead-letter queue is a holding place for jobs that ran out of retries or hit a permanent error. It exists so a failed text becomes a record someone can act on, not a line in a log nobody reads.
Each dead-lettered job should keep:
- The original payload: destination, body and your internal ID.
- The idempotency key, so a manual redrive stays safe.
- The error bucket and code from the last attempt.
- How many attempts ran, and when.
- Which contact or customer it belongs to, so the right person can act on it.
Then decide who owns it. A permanent failure on an invalid number should flow back to wherever the number was collected, so someone can fix it. An opt-out shouldn't be redriven at all. Delete it from the active queue and let your contact record show the opt-out.
Add a redrive tool, even a small one. After you fix a bug or a number, you'll want to replay a filtered set of dead letters. Because each one kept its idempotency key, a replay that overlaps with a late success won't send a duplicate.
What Ready does before your retry logic sees an error
Some failures never reach you as a billing event. Opt-outs and numbers on your Ban list are refused up front and not charged. A number Ready's own sends have already seen as a landline is refused up front on every account, with no charge. A held text is charged only when it sends.
That means your dead-letter queue shouldn't treat a refusal as a billing problem. Refusals for opt-outs and known landlines are free, so you don't need to pre-check each send. Validate a list once when you import it, as the number validation docs describe.
Be clear about one limit. Ready doesn't fail over between carrier providers, so your retry is the only second attempt a failed send gets. Design for that. If a message matters, such as a security code, give your product a fallback channel like email or an in-app prompt after your last retry.
Know what happened after the API said yes
A successful API response means Ready accepted the text, not that a handset received it. Delivery outcomes arrive afterward, and a text can fail downstream even when the send call succeeded. Our post on delivery receipts and the read gap explains what a delivery signal does and doesn't prove, and the inbound webhooks post covers how to receive events. For event names and payloads, use the Ready docs rather than guessing.
Store the outcome against your own message ID, and run a small job that looks for sends with no outcome after a set time. That's your alert for a silent failure.
A short checklist
- Sort errors into temporary, permanent and held, in one mapping table.
- Retry only the temporary ones, with backoff, jitter and a deadline.
- Make one idempotency key per message, reused on every retry.
- Dead-letter what's left, with enough context to act on it.
- Never redrive an opt-out.
- Give critical messages a second channel.
Failure handling is mostly bookkeeping, and the bookkeeping is what keeps a rough hour with your provider from turning into a pile of duplicate or missing texts. The API quickstart is a good place to wire in the first send before you add the rest.