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 stays queued

Queued means accepted, not sent yet. Two usual causes:

1. Pacing. Drip sends space out at randomized intervals on each line, so a large batch drains over time by design.
2. Capacity. A line can hold a new cold contact until it has room to send.

If a message has stayed queued far longer than your batch should take, contact support with the message_id.

Cold sends are waiting for capacity

Capacity is set per line. Excess cold sends wait for a later window rather than erroring, so nothing is lost. If you hit the ceiling regularly, the fix is more lines, not more pressure.

API request limits are a separate thing. A 429 response carries "error": "RateLimitExceeded" and a Retry-After header with the seconds to wait. Sends also have their own budget of 30 messages per 15 minutes per workspace. See rate limits.

A send to one contact is refused

If the contact has Do Not Disturb on, sends to them are refused. Don't retry and don't reroute through another line; remove them from the campaign and add them to your own opt-out list. See opt-out handling.

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 recent baseline: a sharp drop on the same list and copy is a line-health signal. Zero replies across a long run of 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. 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. Rest the line as described in deliverability.

Webhooks stopped arriving

Work through it in this order:

1. Your endpoint must return a 2xx quickly. Do the work after you answer.
2. Check the headers you registered. A deploy that changed how your endpoint checks its secret header drops every delivery as unauthorised. Compare what your endpoint expects with the inbound_webhook headers on GET /v1/workspaces/{id}.
3. Check the URL on the same response. If it is blank, nothing is registered for that workspace. Register it again with PATCH /v1/workspaces/{id}. The steps are in inbound webhooks.

While diagnosing, read GET /v1/messages/{id} for an outbound message. Its status moves from queued to webhook_sent, accepted, sent and delivered, or ends as failed with the reason in error_message.

A retried request sent twice

There is no idempotency header, so a send you repeat after a timeout can go out twice. Before you retry, check GET /v1/messages?workspace_id=...&phone=... for the message you meant to send. If it is there, do not send it again. Keep your own record of each send and its message_id.

Still stuck

Send support the message_id, the message text from the error body, and the timestamp. The X-RateLimit-* headers on each response show how much of your budget is left, which often answers "did my request even arrive".