Put a hard timeout on every SMS API call, take the call off your user's request path, and wrap it in a circuit breaker and a bulkhead so a slow provider can only hurt the texting feature, not the whole product. The failure you're guarding against usually isn't an error. It's a call that hangs, holds a thread, and quietly uses up your capacity.
This post walks through the three patterns in the order you'd add them, with a worked example using stated assumptions. It's about protecting your own app. We make Ready, and nothing here describes failover between providers, because Ready doesn't do that. A breaker tells you to stop calling and try later. It doesn't send the message somewhere else.
Why a slow call is worse than a failed call
A failed call returns in milliseconds, and your code handles it. A slow call holds a connection, a worker and often a database transaction while it waits. Under load, those pile up.
Here's an example with assumed numbers. Say your app handles 50 requests per second, and 10 percent of them trigger a text. That's 5 SMS calls a second. If the provider normally answers in 300 ms, you have about 1.5 calls in flight at any moment. If it starts answering in 30 seconds, you have 150 calls in flight, each holding a worker. If your pool has 100 workers, every request to your app, including ones that never send a text, now queues behind them.
That's the whole problem. A texting dependency took down login, checkout and the dashboard. Timeouts, breakers and bulkheads each cut a different link in that chain.
Step 1: set timeouts on every call
Most HTTP clients default to no timeout or a very long one. Set them explicitly, and set more than one.
- Connect timeout. How long to wait to open the connection. Keep it short, around one to two seconds is a common starting point.
- Read (response) timeout. How long to wait for the response once connected. Choose it from what you observe, not from a guess. Look at your p99 latency for send calls and set the timeout a bit above it.
- Total deadline. A cap on the whole operation, including retries. Without it, three retries with a 10-second timeout each is a 30-second call.
The numbers above are starting points we're assuming for illustration. Measure your own traffic. Ready's docs at https://docs.tryready.com/api describe the API, and any latency figures for your account come from your own logs.
A timeout creates a new question: did the text send? If the request timed out after the provider received it, a retry could send twice. That's what the Idempotency-Key header is for. Send one UUID per message, reuse it on every retry, and a retried POST /v1/messages never sends twice. We cover the details in SMS API idempotency and duplicate texts.
Step 2: take the call off the request path
The cheapest way to keep a slow provider from stalling your app is to not call it while a user waits. Write the intent to your own database, return, and let a background worker make the call.
- In the request, insert a row: recipient, body, an idempotency key you generate, status
queued. - Return success to the user immediately.
- A worker picks up queued rows, calls the API with the timeout above, and records the result.
Now a slow provider makes your queue grow, which you can see and alert on, instead of making your pages hang. Our post on queue design for SMS platforms goes through the table layout and worker behavior. Not every text can be async. A one-time code a user is staring at the screen for is the exception, and that path needs the tightest timeout you can live with.
Step 3: add a circuit breaker
A timeout protects one call. A breaker protects the next hundred. After enough recent failures, it stops calling the provider for a while, so your workers aren't each burning a full timeout to learn the same thing.
A breaker has three states:
| State | What happens | Moves to the next state when |
|---|---|---|
| Closed | Calls go through normally; failures are counted | Failures in a window cross your threshold |
| Open | Calls fail immediately without touching the network | A cool-down period passes |
| Half-open | A small number of trial calls are allowed | Trials succeed (back to closed) or fail (back to open) |
Choices to make, and our assumed example values:
- What counts as a failure. Count timeouts, connection errors and server-side errors (5xx). Don't count a validation error on a bad phone number, or a refusal for a contact who opted out. Those are your data being refused, not the provider being unhealthy. The error codes are listed at https://docs.tryready.com/api/errors.
- Threshold. For example, open when at least half of the last 20 calls failed.
- Cool-down. For example, 30 seconds before the first trial call.
- What happens to a call while open. Leave the row in your queue as
queuedand let the worker skip it. Don't drop it, and don't fail the user's action.
An open breaker doesn't deliver the message by another route. It buys you time. When the breaker closes, your queue drains. If the delay matters to your customers (a time-sensitive alert, for instance), design for it with a fallback channel such as email, which we cover in the SMS critical alert fallback ladder.
Step 4: add a bulkhead
A bulkhead is a separate, limited pool for one dependency. Name a fixed number of workers or concurrent calls that may talk to the SMS API, and nothing else can use them.
- For a queue worker, run texting on its own worker pool or process, with a concurrency cap.
- For in-process calls, use a semaphore. For example, allow at most 20 concurrent SMS calls; the 21st waits briefly and then fails fast.
- Per tenant, if you're a platform. One customer's 50,000-contact campaign shouldn't consume the capacity another customer's appointment reminder needs. Give each tenant a share, or give transactional sends a lane separate from campaigns.
Bulkheads also respect the provider's own limits. If you cap concurrency, you're less likely to trip rate limits, which we describe in SMS API rate limits.
Step 5: make the failure visible
A breaker that opens silently is a bug nobody notices until a customer writes in. Emit a metric when it opens and closes, track queue depth and the age of the oldest queued message, and alert on both. Observability, logging and alerting for SMS lists the signals we'd start with. Also decide, in advance, what your support team tells customers while the breaker is open. A runbook is easier to write on a quiet Tuesday than during an incident, and our provider outage runbook is a starting template.
One more rule specific to texting. When the breaker closes and the queue drains, check the age of each message before sending. A "your driver is arriving" text that's two hours old shouldn't go out. Give each queued message an expiry and drop it, with a log line, once it's stale.
Frequently asked questions
What timeout should I set on an SMS API call?
Measure first. Set the connect timeout to one or two seconds, and set the read timeout just above your observed p99 for send calls. Then add a total deadline that covers any retries. The numbers here are assumptions for illustration, not Ready figures.
Do I need a circuit breaker if I already have retries?
Yes, they solve different problems. Retries handle a brief blip. During a longer slowdown, retries multiply the load on your workers. A breaker stops the retry storm.
Will a circuit breaker send my text through another provider?
No. It stops your calls for a cool-down and leaves the message queued. Ready doesn't fail over between providers, so if you need a second route, you'd build that on your side, or use another channel for urgent messages.
What to do this week
Set explicit timeouts on every SMS call, move non-urgent sends onto a queue, and add one metric for queue age. Add the breaker and the bulkhead once you can see the queue. If you'd like to test the integration against the Ready API, read the quickstart at https://docs.tryready.com/api#quickstart, or see pricing first.