For an SMS API client, set a connect timeout of a few seconds, a read timeout of at least 35 seconds for a send (Ready's own deadline is 30 seconds and it answers 504 itself), and a total deadline that covers all your retries. Reuse one HTTP client so connections stay alive, size the pool to your concurrency, and treat a timed-out send as unknown, not failed. Retry it with the same idempotency key.

We make Ready, so the examples call the Ready REST API with only the request shape we document. The settings apply to any provider. The numbers here are starting points, not measurements of anyone's network, so tune them against your own latency data.

Why SMS sends need their own timeout thinking

Most HTTP calls are safe to repeat. A send isn't. If a request to read a record times out, you ask again. If a request to send a text times out, the provider may have accepted it, queued it and delivered it, with the response lost on the way back. A timeout on a send doesn't mean it failed. It means you don't know.

That changes how you pick the numbers. A timeout that is too short creates more ambiguous sends. One that is too long ties up workers and delays everything behind them. And without any timeout, a stalled connection can hold a thread or a coroutine for as long as the operating system lets it, which can be minutes.

The timeouts to set

One "timeout" setting hides several different waits. Most clients let you set them separately, and you should.

TimeoutWhat it limitsStarting point
ConnectTCP handshake, plus TLS in many clients3 to 5 seconds
ReadWait for response bytes after the request is sent35 seconds or more for POST /v1/messages: Ready may wait up to 30 seconds on the carrier and answers 504 itself. A shorter read timeout gives up just when the send is about to succeed
WriteTime to push the request body out5 seconds, bodies are tiny
Pool or queueWait for a free connection from your own pool1 to 5 seconds
Total deadlineEverything, including retries90 to 120 seconds per message

Connect timeouts can be short, because a healthy network completes a handshake quickly. A connect timeout is also the one failure where you know the request never left, so it's safe to retry. Read timeouts are the ambiguous ones, since the request was sent and you don't know what happened.

The pool timeout deserves a note. If your pool has 20 connections and 50 tasks want one, 30 of them wait inside your process. That wait looks like a network problem in logs, but it's your own queue. Give it a separate, short timeout so you can tell the two apart.

Python with httpx

httpx lets you name each timeout and set pool limits in one place.

import os

import httpx

client = httpx.Client(
    base_url="https://api.tryready.com",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=httpx.Timeout(connect=5.0, read=35.0, write=5.0, pool=2.0),
    limits=httpx.Limits(
        max_connections=20,
        max_keepalive_connections=10,
        keepalive_expiry=30.0,
    ),
)

Create it once at startup and share it. Creating a client per request throws away the connection pool and pays a fresh TLS handshake every time. Our guide to async sending with httpx shows the same client under a concurrency cap.

Go with http.Transport

Go's defaults catch people out. The default transport keeps only two idle connections per host, so a worker pool larger than that opens and closes connections constantly.

package smsclient

import (
	"net"
	"net/http"
	"time"
)

func New() *http.Client {
	transport := &http.Transport{
		DialContext: (&net.Dialer{
			Timeout:   5 * time.Second,
			KeepAlive: 30 * time.Second,
		}).DialContext,
		TLSHandshakeTimeout:   5 * time.Second,
		ResponseHeaderTimeout: 35 * time.Second,
		MaxIdleConns:          50,
		MaxIdleConnsPerHost:   20,
		MaxConnsPerHost:       20,
		IdleConnTimeout:       60 * time.Second,
		ForceAttemptHTTP2:     true,
	}
	return &http.Client{Transport: transport, Timeout: 40 * time.Second}
}

http.Client.Timeout is the total deadline for one call. Pass a context per request as well, so a shutdown cancels in-flight sends. Our Go guide has the full request code.

Keep-alive and pool sizing

Opening a connection costs a TCP handshake and a TLS handshake. Over a long distance that's several round trips before a single byte of your request goes out. Keep-alive reuses the connection for the next request, which is why one shared client matters more than any other setting here.

Size the pool with Little's law: connections in use equal the request rate times the time each request takes. As a labelled example with assumed numbers, 30 sends per second at 0.4 seconds each is about 12 in flight, so a pool of 16 to 20 leaves room for bursts. Don't set the pool to a thousand to be safe. A very large pool lets a retry storm open hundreds of connections at once, and then the provider's rate limit answers with 429s. See our post on SMS API rate limits.

Two more details affect reuse:

  • Idle expiry. Servers and load balancers close idle connections after a while. If your client keeps one longer than the other side does, the next request hits a dead socket and fails. Keep your idle timeout shorter than what the other side allows, such as 30 to 60 seconds.
  • HTTP/2. A single HTTP/2 connection carries many requests at once, so you need fewer connections. Check that your client negotiates it before you assume so.

DNS and cold starts

Every new connection starts with a DNS lookup unless something caches it. With a pooled client that happens rarely. In short-lived processes, such as serverless functions and cron jobs, it happens on every run, so DNS time becomes part of your connect time.

A few things help:

  • Reuse the client across invocations by creating it outside the handler.
  • Know your runtime's DNS cache. The JVM caches lookups according to the networkaddress.cache.ttl security property, and some containers add a local resolver on top.
  • Keep the connect timeout longer than a slow lookup, but short enough to fail over to a retry. A long-lived pool should re-resolve names over time, so a cached address doesn't outlive a change on the provider's side.
  • Test from the environment you deploy to. Alpine images and some container networks resolve names more slowly than a laptop.

Don't hard-code an IP address for the API. You lose the provider's ability to move traffic, and a certificate check against the hostname will fail.

What to do when a send times out

A read timeout or a dropped connection after the request was sent is an ambiguous outcome. Follow one rule: retry with the same Idempotency-Key. Generate one key per message, store it before the first attempt, and send it on every try. If the first request did go through, the retry with the same key doesn't send a second text.

import time

def send(client: httpx.Client, to: str, body: str, key: str):
    # key is created once per text and read from the job row, never made here
    deadline = time.monotonic() + 100.0
    for attempt in range(1, 5):
        try:
            res = client.post(
                "/v1/messages",
                json={"to": to, "body": body, "consent_attested": True},
                headers={"Idempotency-Key": key},
            )
            if res.status_code != 409 or attempt == 4:
                return res
            time.sleep(2 * attempt)   # 409 idempotency_in_progress: still sending, retry the same key
        except httpx.TransportError:
            if attempt == 4 or time.monotonic() + 0.5 * attempt > deadline:
                raise
            time.sleep(0.5 * attempt)

The deadline is the total budget, and it stops retries from stretching one message past it. When retries run out, don't guess. Look the message up with GET /v1/messages before you resend, and see the errors reference for how each status should be handled. A message that never reached the provider and one that did look the same from your side, so the lookup is how you tell them apart. Our posts on idempotency keys and retries and failure handling cover the cases in detail.

Wrapping up

Set separate connect, read, pool and total timeouts, share one client, and size the pool from your real rate and latency. Treat a timed-out send as unknown, store the key before you send, and retry with it. If you log which timeout fired, you can tell your own queue from the network, which is most of the debugging.

When you want to see the request in action, the API quickstart has a first send.