Log every send attempt with a correlation id and the outcome, track a handful of rates rather than raw counts, and alert on changes in those rates instead of on single failures. A single failed text is normal. A jump in refusals, a silent webhook or a spike in segments is the signal worth waking someone for.
This guide is for engineers who already send through an API and want to know when it breaks before a customer says so. It stays general about event shapes, because the exact fields live in the docs. We link the API reference where that matters.
Log the attempt, not the message
Every send should produce one structured log line when you call the API and one when you learn the result. Include:
- your own message id and the
Idempotency-Keyyou used - the tenant or sub-account the text belongs to
- the HTTP status and any error code from the response
- latency of the API call in milliseconds
- the number of segments, if you computed it
- the retry attempt number
Use the idempotency key as your correlation id. It's already unique per logical message and stays the same across retries, so one search finds the whole story. Our post on idempotency and duplicate texts explains why.
Add the same id to the webhook handler's logs when the result comes back. Then a text that never gets a result is a query: attempts with no matching result after a set time.
Redact before you write
Logs outlive the message and travel to third-party tools. Decide what never goes in them.
| Field | Log it? | Better form |
|---|---|---|
| API key | Never | Log a key label or last four characters |
| Message body | Rarely | Hash it, or log length and segment count |
| Phone number | Mask | Keep the last four digits, or a stable hash |
| Contact name | No | Use your contact id |
| Webhook signing secret | Never | Not at all |
| Health details | Never | Keep PHI out of texts entirely |
A phone number is personal data, and a body can hold anything a customer typed. If you need to debug a specific text, look it up by id in your own database rather than reading it from a log aggregator. Ready isn't HIPAA compliant and doesn't sign BAAs, so PHI shouldn't be in the message body in the first place.
The metrics worth tracking
Raw counts hide problems. Track rates per tenant and overall, over a rolling window.
| Signal | What it tells you | Watch for |
|---|---|---|
| Send success rate | API accepted vs. refused | A drop after a deploy |
| Refusal mix | Opt-out, invalid number, quiet hours | One reason jumping |
| API latency, p50 and p95 | Your dependency's health | Tail growth, timeouts |
| Delivery rate | Texts that reached handsets | A tenant diverging from the rest |
| Attempts with no result | Lost or late webhooks | A rising count |
| Webhook handler errors | Your receiver's health | Any sustained rate |
| Segments per message | Encoding drift | A sudden rise (an emoji slipped in) |
| Spend per tenant per hour | Cost and key misuse | A step change |
Delivery tracking is a topic of its own. Our post on delivery rate monitoring for platforms goes deep, and delivery reports explains why a send response isn't a delivery result.
Slice by tenant. An overall rate can look healthy while one customer's rate is poor, and on a multi-tenant product that one customer is the one who writes in.
Separate refusals from failures
Not every non-success is an error. A refusal because a contact opted out is the system doing its job. A 409 for quiet hours means reschedule. A 5xx or a timeout means retry. If all of these feed one "errors" counter, the graph is noise.
Map each response to a bucket in one place: temporary, permanent for this message, or held. Then count the buckets separately. The decision table in retries and failure handling is a good starting point, and the error docs are the source for the codes themselves. Don't hard-code a list from memory.
A rising share of permanent refusals usually means a data problem on your side, such as stale numbers or a list that skipped your opt-out check. A rising share of temporary failures points at the network or the provider.
Alerts that deserve a page
Alert on conditions that need a human, and route the rest to a dashboard. A starting set:
- Spend spike. Segments or cost per hour for one tenant is several times its recent normal. This is the earliest sign of a runaway loop or a leaked key.
- Webhook silence. No inbound events for longer than your quietest normal gap, while sends continue.
- Rising unresolved attempts. Sends with no result after your expected window, climbing.
- Sustained 5xx or timeout rate. Several minutes, not one blip.
- Handler failures. Your webhook endpoint returning errors, since the sender will retry and you may see duplicates.
- Auth failures. A burst of 401 responses after a deploy or a rotation usually means a stale key.
Pick thresholds from your own history. We won't give you a universal number, because a product that sends 50 texts a day and one that sends 50,000 need different ones. Start loose, then tighten after you've seen a week of real traffic.
Page on symptoms users feel and ticket the causes. "Texts aren't arriving" is a page. "Latency p95 rose" is a ticket until it crosses a line.
Reconcile, don't just watch
Alerts catch change. Reconciliation catches silent loss. Run a scheduled job that reads recent messages back with GET /v1/messages and compares them with what your webhooks delivered. Any difference is a missed event to repair. It's a few dozen lines and it turns a quiet gap into a report.
A worked example, with assumptions
Suppose a tenant normally sends about 200 one-segment texts per hour. Assume your alert fires when hourly segments exceed five times the trailing average. A loop bug starts sending the same text over and over, and the alert trips within the hour at 1,000 segments. At $0.012 per segment all-in (the $0.0075 Standard rate plus the $0.0045 carrier fee, excluding screening), you've bounded the damage to one hour of that rate. Without the alert, the loop runs until someone reads the bill. Idempotency keys stop a retry from sending twice, but they won't stop a bug that generates fresh keys, which is why a spend alert matters.
Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.
What to build first
Start with structured logs keyed by idempotency id, one spend alert and one webhook-silence alert. Add the refusal buckets next, then the reconciliation job. To try it on a real account, sign up, send a first text from the API quickstart, and check the pricing page for what each segment costs.