​

Where to look first when a message send fails

​

The four failure surfaces in one diagram

your send
  │
  ├─ the HTTP call itself errored (4xx / 5xx)
  │     → Request Logs          one row per API call, full request + response bodies
  │
  ├─ 202 Accepted, but the message never reached a terminal state
  │     → Delivery Logs         one row per message, lifecycle steps, carrier reasons
  │
  ├─ a window of traffic looks wrong, not one message
  │     → API analytics         per-endpoint / per-key aggregates, latency-spike alerts
  │
  └─ the message changed state, but your system never reacted
        → Settings → Webhooks   delivery attempts, retry history, replay

​

The triage decision tree

​

(a) Send returned 4xx: Request Logs

​

(b) 202 but stuck in queued: Delivery Logs by id

​

(c) sent but never seen by the recipient: terminal state + carrier reason

​

(d) Burst of failures at a time of day: API analytics, then pivot

​

(e) Webhook consumer silently missed events: health panel + replay

​

Per-channel gotchas that change the pane you open first

• WhatsApp template rejection. Two distinct shapes. A pre-send refusal (422 TEMPLATE_NOT_APPROVED while the template awaits provider approval, 400 WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH when variable counts disagree) is a 4xx at send time: Request Logs is the pane, and no Delivery Logs row exists for the attempt. An async Meta rejection after a 202 is the opposite: Request Logs shows a healthy 202 and the Delivery Logs row terminates at rejected with Meta’s reason on the terminal step. Fix the template or the variable shape, then resend from your normal send path.
• SMS carrier filtering. Filtering happens downstream of the 202, so it never shows in Request Logs. The Delivery Logs terminal step names the reason when the carrier returns one; silent filtering shows as failed or as submitted-no-receipt with no reason at all. When the reason is absent, score the body before your next send with the Deliverability Lab and check your registration posture in the 10DLC registration guide; unregistered high-volume traffic is filtered by design.
• RCS fallback to SMS. When a smart-send arms a fallback chain, an undelivered RCS primary spawns a second send on the fallback channel. Delivery Logs then shows two rows to the same recipient: the rcs row terminal-failed and an sms row behind it. Read the pair before you call the send a failure; the cascade working as designed is a red row followed by a delivered one. The chain mechanics are in smart-send fallback chains.
• Email DNS absent. Sends from a domain without SPF, DKIM, and DMARC either fail at the domain gate or bounce after submission; retrying does not help because the fix is DNS records, not the payload. The Delivery Logs reject names the bounce class; the domain row in the console lists the exact missing records, and email DNS auto-configuration can create them for Cloudflare-hosted zones.

​

Worked examples

​

One SMS stuck in queued

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "+14155550100",
    "body": "Your Devotel Orbit verification code is 493021."
  }'

{
  "data": { "id": "msg_2c4d6e8f0a1b3c5d", "status": "queued" },
  "meta": { "request_id": "req_7b3f9a21" }
}

1. The 202 rules Request Logs out; open Developer → Delivery Logs instead and paste msg_2c4d6e8f0a1b3c5d into the search box. The Message id match strip pins the one row: channel sms, direction outbound, status queued.
2. Click the row. The drawer shows the Accepted step at created_at and stops: no Routed step, no Submitted step, no error on any step.
3. Compare created_at to now. Minutes old means the lifecycle can still be running; refresh before concluding anything. Hours old with no routing step means the send stalled between acceptance and routing.
4. Confirm from a script with the same vocabulary the page uses: GET /api/v1/messages?message_ids=msg_2c4d6e8f0a1b3c5d returns the row with status: "queued", a created_at, and no sent_at.
5. Capture msg_2c4d6e8f0a1b3c5d, req_7b3f9a21, and created_at, and escalate per the next section.

​

One WhatsApp template rejection

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/whatsapp" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+4915123456789",
    "template_name": "order_shipped_v2",
    "template_params": ["{{1}}", "{{2}}", "{{3}}"]
  }'

{
  "error": {
    "code": "WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH",
    "details": "template declares 2 positional placeholders; request supplied 3 template_params",
    "docs_url": "/errors/WHATSAPP_TEMPLATE_VAR_COUNT_MISMATCH"
  }
}

1. Open Developer → Request Logs, filter to your key prefix, status 4xx, path /messages/whatsapp. The row is there in amber with a 400.
2. Open the row and read the response body: error.code names the refusal, error.details says the template declares two placeholders and the request sent three. That is the whole fix; Delivery Logs has no row for this attempt because the 4xx never created a message.
3. Contrast with the async shape: had the same request returned 202 and Meta later refused the template, Request Logs would show a green 202 and Delivery Logs (channel whatsapp, status rejected) would carry Meta’s reason on the terminal step. Same operator question, different pane.
4. Fix the variable count (or wait out template approval for TEMPLATE_NOT_APPROVED), resend, and confirm the new attempt reaches a terminal delivered in Delivery Logs.

​

When to escalate

• A row sits non-terminal past the delivery window with no routing or submission step.
• A carrier-rejection cluster persists after you rotate sender, template, or body, and the terminal-step reasons point at carrier-side blocks.
• Request Logs shows 5xx rows from Orbit itself; capture several request ids so support can pull the traces.
• Replays succeed but deliveries fail again identically, which puts the fault at your consumer rather than the bus; capture one event id and the attempt history anyway, because that contrast is the diagnosis.

• The request id (req_…) from the Request Logs drawer or the API response’s meta.request_id.
• The message id (msg_…) from the send response or the Delivery Logs row.
• Exact timestamps: created_at, sent_at, and the terminal stamp, as displayed.
• The channel and direction, plus error_code and error_message from the terminal step when present.
• The API key prefix that authenticated the send, and the recipient as shown on the row.

​

See also

• Delivery Logs console — the per-message lifecycle, filters, and shareable URLs
• Request Logs console — per-call payloads, filters, and the live tail
• API analytics dashboards — the aggregate view and the alert-to-request drill
• Operate a webhook endpoint — health panel, retries, and replay
• DLR webhook consumer guide — per-channel delivery-receipt semantics
• Where to look first when an outbound call fails — the sister guide for voice