Troubleshooting hub
The Reference group in the sidebar is a flat list of well past 60 pages, and most of them are runbooks. This page exists so you never have to scan that list: every troubleshooting page lives in one of the sections below, grouped by the surface it works on. The Reference index itself — error codes, webhook events, glossary, and FAQ — lives at the top of the sidebar group; this hub indexes only the runbook pages.One link basename changed shape over time: the
message stuck in queued page answers to the
reference/troubleshooting route because it was the first runbook. Every
other runbook lives under /troubleshooting/<slug>.Messaging queues and receipts
Messaging queues and receipts
Diagnose a message stuck in the pre-send queue, one accepted by the provider
that never reports a delivery outcome, and the recovery pattern when the
carrier receipt itself goes missing.
- Message stuck in queued — a message that cannot get out of the pre-delivery stage.
- Message sent but no delivery receipt —
the row reached
sentbut adelivered/undeliveredoutcome never lands. - Recover a failed or late DLR — retry and backfill a missing delivery receipt.
- Message undelivered or failed — a terminal non-delivered outcome and what to do next.
Numbers and sender identity
Numbers and sender identity
Buy numbers, get sender IDs approved, work warming caps, and handle India DLT
or 10DLC gates.
- Number purchase failure — inventory races and provisioning retries.
- Number warming caps —
DAILY_CAP_EXCEEDED,WARMING_QUOTA_EXCEEDED, andNUMBER_MPS_EXCEEDED. - Sender ID rejected before send —
the pre-send
SENDER_ID_NOT_REGISTERED/SENDER_ID_NOT_APPROVEDgate. - Sender-ID registration rejected or expired — resubmit or reactivate a declined sender.
- India DLT gate — a 422 with a
dlt_template_id/dlt_entity_idrequirement. - 10DLC campaign rejected — resubmit a campaign the carrier declined.
Voice
Voice
Triage SIP trunk health, call quality, blocked destinations, and TCPA dialing
windows.
- SIP trunk — registration, health, failover, and capacity.
- Voice call quality — one-way audio, dead air, jitter, and PDD.
- TCPA blocked calls — the dialing window a blocked call fell outside.
- Suspect voice destination — destination and emergency blocks.
- Failover and failback — a call that fails right after a regional move.
Compliance and deliverability gates
Compliance and deliverability gates
DNC, consent receipts, destination blocks, and the strict-sender-id FQDN
gate.
- DNC pre-flight returns 403 —
DNC_SYNC_NOT_ENABLEDon a send gate. - CONSENT_RECEIPT_INVALID — a caller receipt the API cannot verify.
- SMS destination blocks — the spending and destination gate for SMS.
- Strict sender-ID FQDN gate —
SENDER_INVALID_FOR_DESTINATIONwhen strict mode rejects a custom sender.
Webhooks
Webhooks
Delivery retries, DLQ and replay, endpoint creation errors, and duplicate
events.
- Failed webhook deliveries — retries, DLQ, and replay.
- Webhook endpoint creation errors — shape and permission errors when registering an endpoint.
- Duplicate webhook events — consumer-side dedup of repeated deliveries.
Verify
Verify
OTP sends and checks, plus the TOTP/push/passkey/backup-code factor suite.
- Verify OTP — a send or a check that fails.
- Verify factor suite — TOTP, push, passkey, and backup codes.
Email
Warmup, bounces and complaints, DNS verification drift, and inbound routing.
- Email bounces and complaints — reputation and suppression follow-ups.
- Email DNS drift — verification drift and recovery.
- Inbound email never routes — parse domain match rules and trigger issues.
Billing and account gates
Billing and account gates
Spend caps, insufficient balance, and billing-pause blocks on outbound.
- Spend-cap refusals — daily caps per channel.
- INSUFFICIENT_BALANCE — the 402 that blocks a send when credits cannot cover it.
- Billing-gate outbound blocks — recovery from the pause block.
Platform roads and queues
Platform roads and queues
Auth and IP allowlists, schema readiness, rate limits, and import/flow
failures.
- Authentication and IP allowlist — key mode and IP-allowlist failures.
- Tenant schema incomplete — the 503 that gates a route while the schema finishes.
- Rate limits and cool-downs — 429 cooldown recovery.
- Import jobs — an import that fails or stalls.
- Flow executions failed — a flow whose execution returned an error.
Channels and integrations
Channels and integrations
Inbound SMS/RCS/WhatsApp route misses, RCS undelivered, and Telegram.
- Inbound SMS no route — inbound to your number never arrives.
- Inbound WhatsApp or RCS no route — an inbound message with no route assignment.
- RCS undelivered — a message that never reached an RCS-capable device.
- Telegram channel errors — connect, push, and mutual-hand-off errors.
Everything else
Everything else
Remaining runbooks for agent queues, conversations, co-browse, and quarantine.
- Agent eval-queue failures — an eval that stalls or fails to start.
- Conversation merge refused —
WEAK_IDENTITY_MATCH_REQUIRES_CONFIRMATION. - Co-browse stuck — a session that never hands off.
- Suspicious or empty queue — an order or import stuck in an enqueued state.
- Quarantined media file — the
FILE_SCAN_QUARANTINEDoutcome. - DSAR export retry — requeue when a data-subject export fails.
Where error codes fit in
When the failure is a specificcode on the API envelope, match that code
against the Error Code Reference first; pick the
runbook from the section above once you know the surface.
How to use a runbook
Every page follows the same shape — a cause table that maps symptoms to fixes, a full-error sample you can paste in a ticket, a decision checklist, the fixes you should NOT try, and when to escalate. Anything in this list matches that pattern; pick one, do not freestyle. For a failure that does not map to one of the runbooks, open a ticket with the steps you tried, thecode from the API envelope when present, and the
output of the endpoint you hit.