Troubleshooting

Each section starts from the symptom you're seeing. Error-code specifics live in errors and status codes; this page is the diagnostic layer on top.

A message sits in pending

Pending means accepted and scheduled, not sent. Three usual causes, in order of likelihood:

1. The drip delay and send window. A drip send schedules about 10 minutes out and delivers inside the org-local window (9:00 to 18:00 by default). A message queued at 8pm sends the next morning.
2. Pacing. Sends on a line space out at randomized intervals, so a large batch drains over hours by design. queue_depth on GET /v1/devices shows the backlog.
3. Capacity. A new cold contact past the line's daily_cap waits for headroom rather than failing.

If a message has sat through an open window with available_today positive on an online line, that's a real fault: contact support with the message_id.

The line is out of capacity

available_today: 0 on GET /v1/devices means the line has reached today's new-contact cap. Remember what is not capped: replies and anyone you have messaged before send fine regardless. Excess cold sends queue for the next window rather than erroring, so nothing is lost; if you hit the ceiling regularly, the fix is more lines, not more pressure. The split between API rate limits (429 rate_limited, retry after retryAfter) and sending capacity is explained in rate limits.

A send to one contact is refused

If the contact opted out, on any line in your account, at any point in the past, sends to them are refused. Don't retry and don't reroute through another line; remove them from the campaign and sync your CRM suppression. Opt-out handling covers how suppression propagates.

409 no_online_device

An instant send needs an online line and none was eligible. Check status on GET /v1/devices; a drip send would have queued instead, which is usually the right fallback for anything that can wait ten minutes.

Deliveries look normal but replies stopped

The most misread signal in outbound messaging. Delivery receipts stay clean while a degraded line quietly stops landing in front of humans. Compare the line's reply rate to its own 7-day baseline: a 40% drop on the same list and copy is a line-health signal, and the platform's own monitoring (device.health_changed, state imessage_collapse) watches for exactly this. Zero replies across 150+ sends on a line that used to reply is the same signal, louder; flag it to us the same day.

More messages falling back to SMS than usual

First check the list: a different source mixes in more non-iMessage recipients, and POST /v1/capability before sending settles it. If the list is comparable to previous sends, treat it as a line-health signal; a line under an Apple-side throttle shows exactly this pattern, and the cooldown machinery in rate limits is the response.

Webhooks stopped arriving

Work through it in this order:

1. Your endpoint must return a 2xx within 5 seconds. Three consecutive failed deliveries auto-disable the endpoint; re-enable it from the dashboard delivery log.
2. Check signature verification. A deploy that changed your secret handling silently drops every event as invalid. The verification steps are in webhooks.
3. Use send-test and replay from the dashboard delivery log to confirm end to end.

While diagnosing, poll GET /v1/status/{id} so nothing is lost.

A retried request sent twice

It didn't, if you send an Idempotency-Key header on every send. A repeat within 24 hours replays the original response with Idempotent-Replay: true: treat it as success. If you're not sending the header yet, start; it's the difference between safe and unsafe retries.

Still stuck

Send support the message_id, the error_code from the response, and the timestamp. Your key's own call log is also visible at GET /v1/usage, which shows per-endpoint success rates and often answers "did my request even arrive".