When your SMS provider has an outage, do four things in order: confirm it's the provider and not you, stop sending and queue instead of dropping, tell your users plainly, then retry with idempotency keys once it recovers. Afterwards, reconcile what actually went out against what you meant to send.

Our own position matters here. Ready does not fail over between carrier providers. We're a thin layer over a messaging provider, so if that layer is down, sends fail for us too. This runbook is what you build on your side, whichever vendor you use.

Detect it before your users do

Alert on your own send results, not on a status page. Track the share of sends that return an error or a timeout over a rolling window, and the time from send to delivery report. A sudden jump in either is your signal.

Check three things before you call it an outage:

  1. Is your API key still valid and your balance funded?
  2. Do a few sends to your own test number succeed?
  3. Is the failure on every number, or only one carrier or one 10DLC campaign?

Registration problems and carrier filtering look like an outage but aren't one. Our observability post covers the metrics, and the error codes docs tell you which failures are yours.

Queue instead of dropping

The worst move is losing the message. Put every outbound text in your own durable queue before you call the API, with a state: pending, sent, failed, parked. When the error rate crosses your threshold, flip a switch that stops dispatching and leaves items pending. Our queue design post goes deeper.

Give each queued item an expiry. A login code is useless after ten minutes. A shipping notice can wait a day. Decide per message type, ahead of time, which ones expire and which ones wait.

Tell your users

Silence reads as a bug in your product. Show a banner in your app when you've paused sending, and say what is affected and what isn't. For time-critical flows like codes, offer another path, such as email or an in-app prompt. Don't promise a recovery time you don't control.

Retry safely with idempotency

Recovery is when duplicates happen, because some requests timed out after the provider accepted them. Every send gets an Idempotency-Key header, one UUID stored with the queued item, reused on every retry of that item:

POST https://api.tryready.com/v1/messages
X-API-Key: <key>
Idempotency-Key: 6f1c9a0e-3b6e-4a53-9d5f-2f0b6a1d7c11
Content-Type: application/json

{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true}

A retried request with the same key never sends twice. Drain the queue slowly. Release at a fraction of your normal rate and raise it while errors stay low, since a flood after an outage can trip carrier throughput limits. See retries and failure handling for which errors to retry and which to park.

Watch quiet hours on the way out

A long outage can push the backlog into the night. A 1:1 or API text is held only if the quiet-hours window opens within 6 hours. Otherwise the API answers 409 QUIET_HOURS_BLOCK and the text is not sent, so your queue has to send it again once the window opens.

What Ready does and doesn't do

SituationReady
Provider outageNo failover between carrier providers. Sends fail until the provider recovers.
Duplicate protectionYes, with the Idempotency-Key header.
Held and refused textsOpt-outs and ban-list numbers are refused and not charged. A held text is charged only when it sends.
Your own queue and user messagingYours to build.

Reconcile after the incident

Once things are stable, replay every pending or unknown item with the Idempotency-Key you stored for it. Read the answer, not only the header. Idempotent-Replayed: true also marks a stored refusal, so a 2xx with success: true means it already went out and nothing was sent or charged again; a replayed 202 send_outcome_unknown or 409 idempotency_outcome_unknown means check GET /v1/messages before deciding; a replayed refusal (such as 409 QUIET_HOURS_BLOCK or a 503 that says nothing was sent) did not go out, so give that item a new key and send it again. Any other answer is the send happening now, with the opt-out and quiet-hours checks the send path always runs. No matching by recipient and time. The limit is the key retention window in the Idempotency docs: for an item older than that, a replay is a new send, so walk recent messages with GET /v1/messages, paged with before_id, and decide to resend or expire. Before resending to anyone who might have replied STOP during the outage, check GET /v1/opt-outs/:phone.

Then write the review: when you detected it, how long sends were paused, how many items expired, and what you'd change. A runbook only improves if you update it.

Next step

Read the API quickstart, add the idempotency header to your send path, and rehearse a pause once in staging.

Frequently asked questions

Does Ready fail over to a second provider?

No. Ready doesn't fail over between carrier providers, so build queueing and retry on your side.

Can a retry send the same text twice?

Not if you send the same Idempotency-Key header on every retry of that message.

Should I retry every failed text?

No. Retry timeouts and server errors after a pause. If a 503 says nothing was sent, use a new key for the retry, because the refusal is stored under the old one. Park the rest, such as opt-outs or bad numbers, for review.

How do I know what was sent during the outage?

Read GET /v1/messages and compare it with your own queue records.