Skip to main content

​
Troubleshooting hub

The Reference group in the sidebar is a flat list of well past 70 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.
The queued-lane deep dive is split deliberately across two pages: message stuck in queued owns the queued cause table and the status decoder (it answers to the reference/troubleshooting route because it was the first runbook), and message parked before sending owns the other pre-send holds — scheduled, pending, and quiet-hours. Every other runbook lives under /troubleshooting/<slug>. Webhook failures split two ways as well: the Webhook delivery failures accordion below owns endpoint creation, signature verification, DLQ recovery, and dedup, while the Webhooks accordion keeps only the ordering and supersede semantics.
Diagnose an inbound digital conversation that holds in the pending lane, one that opens but never assigns an agent, or an auto-close sweep that closes before the window you configured.
  • Inbox assignment stuck pending and auto-close timing — the routing/queue/presence split on an inbound pending thread, the pending-replies supervisor queue, and the auto-close idle-window checks.
  • Ticket attachment storage unavailable — the 503 ATTACHMENT_STORAGE_UNAVAILABLE on an Inbox attachment upload: why it is a storage-backend fault and never a validation problem, the backoff-then-escalate path, and the request id + checksum bundle support needs.
  • Attachment and audio size caps — the deterministic ATTACHMENT_TOO_LARGE (422/413) and AUDIO_TOO_LARGE (400/413) rejections: per-surface byte ceilings, shrink-re-encode-split fixes, and the never-retry direction.
Diagnose a visitor-side capture surface that records nothing, plays back empty or corrupt, or loses uploads on its way to durable storage — session replay first.
  • Session replay failures — empty or forever-spinning playback, SESSION_REPLAY_OFFLOAD_FAILED (503) on the overflow spill to object storage, CORRUPT_SESSION_REPLAY on a drifted stored shape, capture-time privacy masking, retention/purge and abuse-backstop semantics, the single-active-recording invariant, and the client-buffered-then-loss behaviour when the widget capture endpoint is unreachable.
Decode a degraded provider tile on Settings → Presence — what each badge means, what caused it, and the exact fix.
  • Presence federation degraded states — Reconnect required (the OAuth grant died — reconnect the named integration; includes the Reconnect Microsoft 365 CTA), Retrying, Unrecognised value, and Waiting for first sync, with the graceful-fallback behaviour and the escalation paths.
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 — the owner of queued as its own state: the one-page debug ladder, full cause table, per-second-vs-period 429 escalation triggers, DLR-recovery-vs-DLQ-replay disambiguation, escalation path, and status decoder.
  • Message parked before sending — the matrix for the other pre-send holds: scheduled, pending, and quiet-hours.
  • A scheduled message that never fired — the past-send_at row that stays scheduled: split the wall-clock branches from the held-gate branches (quiet hours, compliance profile, sender resolve), rule out a cancellation race, and escalate the drain.
  • Message sent but no delivery receipt — the row reached sent but a delivered/undelivered outcome 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.
  • Campaign and journey enrollment errors — AUDIENCE_TOO_LARGE, JOURNEY_VALIDATION_FAILED, and RESUME_FAILED.
  • Campaign and conference state-machine transition errors — the 409 family that refuses a launch, approval, lock, or take-over when the object moved on: CAMPAIGN_NOT_DRAFT, CAMPAIGN_NOT_PENDING_APPROVAL, CONFERENCE_STATE_UNRESOLVED, the generic INVALID_STATE_TRANSITION, and the softswitch-only INVARIANT_VIOLATION. Map the legal transition, re-read the state, re-issue once.
  • Fan-out and upload errors — EMAIL_SEND_FAILED_ALL, ALL_CHANNELS_FAILED, and file-upload rejections.
  • Media upload failed — the 502 MEDIA_UPLOAD_FAILED on WhatsApp media send/retrieve, the generic file-upload API, and compliance document upload; decode the stage the message names and split retry from escalate.
  • Channel unavailable and fallback exhausted — the 422/503 CHANNEL_UNAVAILABLE when no fallback route is configured or every hop in the ladder failed; name the failing hop, then edit the chain in Settings → Channels.
  • Validation gate codes — the deterministic 422 family: INVALID_PHONE_NUMBER, INVALID_FROM_NUMBER, MISSING_REQUIRED_FIELD, and INVALID_EMAIL. Decode the envelope, pre-flight with number lookup and an E.164 formatter, fix the named field once.
  • Channel and conversation pre-send refusals — the deterministic channel/conversation-naming rejects CHANNEL_REQUIRED, CHANNEL_COMING_SOON, CHANNEL_NOT_REPLYABLE, CONVERSATION_NOT_FOUND, and CONVERSATION_MISMATCH on POST /api/v1/messages and the POST /notify cascade — pass a valid channel, ask support for gated channels, give the right conversation_id or drop it, and never loop the retry.
  • Template has no variant for the channel — the 422 NO_VARIANT_FOR_CHANNEL send gate.
  • Fallback chain names a channel with no variant — the authoring-time VALIDATION_ERROR on fallback_chain.
  • Sender resolution and pool errors — SENDER_REQUIRED, SENDER_POOL_NOT_FOUND, NO_SENDER_CONFIGURED, and the numeric-sender ownership pair 422 SENDER_NOT_OWNED / 503 SENDER_OWNERSHIP_CHECK_UNAVAILABLE.
  • Sender pool resolved but empty — SENDER_POOL_EMPTY: the pool exists but has no members to draw from.
  • Pool spread and anti-snowshoe alerts — pool spread too thin or volume that outgrew the pool.
  • Inbound SMS not recording — inbound MO messages or DLRs that never reach your tenant.
  • SMPP bind rejects and command_status codes — decode bind_*_resp rejects (ESME_RINVPASWD, ESME_RINVSYSID, ESME_RINVBNDFMT) and submit_sm_resp nacks (ESME_RTHROTTLED, ESME_RINVDSTADR, ESME_RINVMSGLEN), plus receipt-never-arrives and the receiver-side MO inbox toggle.
  • Short link not resolving or LINK_NOT_FOUND — split a branded redirect 400/404 from POST /public/lp/:code/convert’s LINK_NOT_FOUND, then verify publication, expiry, target scheme, and rate limits.
Team Chat and huddle states that look broken but are degrade-open semantics, plus the escalation bundle and the fixes that never help.
  • Team Chat and Huddle state surprises — an empty-then-fine who’s-online rail (the three presence calls that degrade to 200-with-empty on transient Postgres, PgBouncer timeouts, and tenant-schema provisioning gaps), presence-vs-message asymmetry between seats, a reaction that is acknowledged but reappears after a cache outage, a huddle that lingers as live with no one in it until the read-path self-heal or a rejoin runs, a 409 CONFLICT when joining a huddle that is ending, Team Chat attachments on the shared storage plane, and what not to try.
Buy numbers, get sender IDs approved, work warming caps, and handle India DLT or 10DLC gates.
  • Number purchase failure — inventory races and provisioning retries.
  • Connectivity SIM events — the seven connectivity_sim.* webhook family: usage-warning vs limit-exceeded quota gates, the ordered → activated ⇄ suspended → terminated lifecycle decoder, and the silent-stream checklist when the events stop arriving.
  • Bulk purchase rate-limited by the carrier — the CARRIER_RATE_LIMITED per-row marker on a partially-completed buy-bulk batch: the breaker skipped the remaining rows without a carrier call, so retry only the failed[] slice after a few seconds — never the whole batch.
  • Port-out rejected or carrier-refused — the 401 PORT_OUT_PIN_MISMATCH PIN gate, 502 CARRIER_PORT_OUT_FAILED on a carrier refusal, and 422 PORT_OUT_NOT_SUPPORTED when the number moves through support.
  • Number warming caps — DAILY_CAP_EXCEEDED, WARMING_QUOTA_EXCEEDED, and NUMBER_MPS_EXCEEDED.
  • Sender ID rejected before send — the pre-send SENDER_ID_NOT_REGISTERED/SENDER_ID_NOT_APPROVED gate.
  • Numeric sender owned by someone else — the 422 SENDER_NOT_OWNED cross-org ownership gate and its fail-closed 503 sibling.
  • Number masking and proxy-session failures — a masked proxy session that will not bind, forwards inbound-only, bridges the wrong call leg, or drifts on expiry.
  • Number lookup and messaging service failures — LOOKUP_FAILED on the number-lookup endpoints and the resolver codes MESSAGING_SERVICE_RESOLUTION_FAILED / MESSAGING_SERVICE_NOT_FOUND.
  • Lookup per-field verdicts — a 200 response where a fields= data package came back coming_soon, not_implemented, or error; decode the status bucket, map the field to its provider, and split retry from escalate.
  • Sender warm-up pacing — the advisory warm-up meter on alphanumeric sender IDs and international long codes: a stalled or slow sender with no 429, the reputation-kernel tiers, and the pace-vs-spread fix paths.
  • Sender-ID registration rejected or expired — resubmit or reactivate a declined sender.
  • India DLT gate — a 422 with a dlt_template_id/dlt_entity_id requirement.
  • 10DLC campaign rejected — resubmit a campaign the carrier declined.
  • 10DLC not registered — the pre-send TEN_DLC_NOT_REGISTERED gate on a US 10-digit long code sender with no approved TCR brand+campaign registration.
  • US toll-free sender blocked with TFV_REQUIRED — the 422 TFV_REQUIRED gate on a toll-free number before Toll-Free Verification is approved, and how to handle a pending or rejected review.
  • Sender and asset preflight gates — MMS_NANP_ONLY on a non-NANP MMS, NOT_SMS_CAPABLE on a sender that cannot carry SMS, TFV_LINT_BLOCKED on a toll-free filing the content lint refused, and LOA_NOT_SIGNED on a hosted-messaging order.
Triage SIP trunk health, call quality, supervisor coaching surfaces, blocked destinations, and TCPA dialing windows.
  • SIP trunk — registration, health, failover, and capacity.
  • Outbound calls rejected with SBC_UNAVAILABLE — the 503 on POST /api/v1/voice/calls and on dialer-dispatched outbound legs: which side owns the cause (your SBC, the upstream carrier, or a transient platform blip), the trunk-record debug ladder, the fix-vs-retry decision table, and the request_id + trunk_id bundle support needs.
  • SIP credential not registered on click-to-call — the 412 SIP_CREDENTIAL_NOT_REGISTERED pre-flight refusal: the softphone behind the credential has no registration inside the five-minute window; work the per-client registration ladder and re-dial.
  • Voice call quality — one-way audio, dead air, jitter, and PDD.
  • Voice inference credential rejected — the 422 VOICE_CREDENTIAL_PROVIDER_REJECTED on registering or rotating a BYO TTS/STT provider key.
  • Voice model credential rejected — VOICE_CREDENTIAL_PROVIDER_REJECTED on registering or rotating a BYO TTS or STT provider key: resolve the credential validation gate with a reissued key or a provider-side permission fix.
  • Secure-payment capture failures — the five SECURE_PAYMENT_* codes on the agent-assisted in-call capture — a missing Jambonz bridge leg, an already-active session, and the four-digit card_last4 mask gate.
  • Payment-mandate confirmation failures — MANDATE_CHARGE_FAILED, MANDATE_SPEND_UNVERIFIABLE (503 fail-closed on the cumulative cap), and IDEMPOTENCY_CONFLICT (409 — a reference reused for a different cart) on the in-call AP2 agentic-payment confirmation.
  • Supervisor takeover, whisper, and barge failures — the SUPERVISOR_* 500s, the already-active-takeover 409, and the supervisor.takeover_failed webhook.
  • In-call AI handoff, deflection, and follow-up failures — HANDOFF_FAILED, DEFLECTION_FAILED, and FOLLOWUP_SEND_FAILED on the three in-call AI exit lanes.
  • Voice call park orbit — PARK_SLOTS_FULL, PARK_SLOT_OCCUPIED, and PARK_ALREADY_RETRIEVED.
  • Voice transfer target restricted — the 403 VOICE_TRANSFER_TARGET_RESTRICTED on a transfer, warm transfer, park, or dialer-scheduled step: tell the per-agent transfer policy gate from a routing misconfiguration, and fix the control you own.
  • MCID flag failures — MCID_INVALID_DIRECTION (outbound call), MCID_CALL_TOO_OLD (aged past the 7-day window), the 404 on an unknown call ID, and the owner/admin role gate on the malicious-call trace export.
  • Conference lifecycle failures — rooms stuck open, legs that drop, and missing end reasons.
  • Call flip and call pickup — FLIP_* handoff rejects and PICKUP_* claim-race rejects.
  • Dialer modes not advancing — preview, power, and predictive campaigns that stop pulling contacts.
  • TCPA blocked calls — the dialing window a blocked call fell outside.
  • State mini-TCPA blocked calls — TCPA_STATE_DIALING_WINDOW_BLOCKED on per-state dialing overlays.
  • FCC AI-voice consent gate — 422 FCC_AI_VOICE_WRITTEN_CONSENT_REQUIRED on AI, TTS, and cloned-voice calls — read the reason enum, work the audit queue, and attach the written-consent evidence.
  • Pre-send gate chain blocks an outbound campaign — read the pre-send screen verdict, separate hard fails from warns, and re-submit.
  • TCPA voice-guard sentinel breadcrumbs — trace a 422 TCPA_FEDERAL_DIALING_WINDOW_BLOCKED back to the dial gate that held it via the Sentry breadcrumb.
  • Suspect voice destination — destination and emergency blocks.
  • Ring-group chain cycles — the 422 INVALID_RING_GROUP_CYCLE a create/update fires when re-ordering members would loop a group back to itself; also covers pay-by-link reachability and the archival channel gate on one page (a cross-surface misconfiguration triage).
  • STIR/SHAKEN attestation stuck at C — spam-likely labels, delegate certificates, and branded-calling overrides.
  • STIR/SHAKEN never measured — the first check: read the policy defaults, confirm the inbound reporting fields, and measure your posture before diving into downgrade causes.
  • Queue capacity gates — 503 QUEUE_DEPTH_CAP_REACHED on queue entry and the 422 overflow-chain codes on queue config writes.
  • Disposition and wrap-up errors — the dispatch-blocking 422 DISPOSITION_REQUIRED gate, the catalog-scoped 404 DISPOSITION_CODE_NOT_FOUND (per queue) vs tenant-wide 404 DISPOSITION_TAG_NOT_FOUND split, and the 409 NOT_IN_WRAPUP presence mismatch — tell each apart and post exactly one valid re-try.
  • Queue SLA forecast callback gate — 503 + slaCallbackBlocked: true on queue entry: forecast breach vs head-of-line trip, suggest-vs-block posture, and callback-dispatcher wiring.
  • Public queue booking failed — 500 BOOKING_FAILED on the public queue self-booking POST: transient server-side failure vs a slot taken between the availability read and the booking, one-retry-then-poll, and the request-id escalation bundle.
  • Voice biometrics failures — the sidecar 503/500 codes on enroll and verify (VOICE_BIOMETRICS_TIMEOUT, VOICE_BIOMETRICS_UNAVAILABLE, VOICE_BIOMETRICS_AUTH_FAILED, VOICE_BIOMETRICS_ERROR), the operator-side CONFIGURATION_ERROR, and the fail-closed vs step-up decision for an outage.
  • Transcription, synthesis, and deepfake failures — STT_TRANSCRIPTION_FAILED / TTS_SYNTHESIS_FAILED on the uploads + agent pipeline, the transcript not-yet-produced 422s vs read-side 5xx split, DEEPFAKE_DETECTED (classifier, not consent), and the *_SUMMARY_LLM_MALFORMED 502s.
  • IVR NLU classifier and slot-extraction failures — IVR_CLASSIFY_LLM_ERROR and IVR_SLOT_EXTRACT_LLM_ERROR 503s from the conversational IVR NLU layer: re-prompt the caller, fall back to a DTMF digit menu, or drop to a queue; flip the flow to DTMF-only when the NLU path flaps.
  • Agent outbound-call and voice-clone guard codes — the pre-origination agent toggle 409 (OUTBOUND_CALLING_DISABLED), the reserved GUARDRAIL_VIOLATION triage, and the VOICE_CLONE_CONSENT_REQUIRED 422 gate.
  • Voice agent dispatch eligibility — VOICE_AGENT_MISSING, VOICE_AGENT_UNAVAILABLE, and VOICE_OPERATOR_LIMIT_EXCEEDED refusals when a voice queue cannot place an agent on a call: check the agent assignment, verify the operator concurrency, and retry the dispatch.
  • Failover and failback — a call that fails right after a regional move.
  • VOICE_GATEWAY_ERROR at call-send — the 502/503 gateway refusal across outbound dispatch, greeting synthesis, and mid-call actions — transient vs deterministic split, retry-safety, and the support bundle.
  • Hot-desking sign-in rejects — HOT_DESK_RACE, HOT_DESK_NO_ACTIVE_SESSION, and the session-ledger codes.
Diagnose room lifecycle failures, degraded video quality, recordings, and SIP dial-out. The VIDEO_* family (30+ codes across the error-codes reference) is indexed here.
  • Video room lifecycle failures — join-token refusals, capacity 400s, lobby gating, and agent dispatch errors, including why a persistent room still ends: the ten-minute empty-room close and the 4-hour expires_at.
  • Video guest chat refusals — VIDEO_CHAT_GUEST_FORBIDDEN, VIDEO_CHAT_LOBBY_HELD, and VIDEO_CHAT_LOBBY_CHECK_UNAVAILABLE on the anonymous guest chat send — the fail-closed tenant-resolution, lobby-admission, and degraded gates.
  • Video waiting-room and lobby errors — the waiting-room denial path: VIDEO_CHAT_LOBBY_HELD for a guest the host has not admitted, VIDEO_CHAT_GUEST_FORBIDDEN for a token the room cannot match, the transient VIDEO_CHAT_LOBBY_CHECK_UNAVAILABLE / VIDEO_CHAT_POLICY_UNAVAILABLE 503s, and the host-side VIDEO_WAITING_ROOM_FAILED / ADMIT_FAILED / DENY_FAILED operation faults — with the host and guest ladders and the escalation bundle.
  • Video room features: chat, polls, Q&A, invites, RTMP — the feature-level VIDEO_* codes — chat policy blocks, polls, invites, moderation, hands/spotlight/whiteboard, RTMP egress, and the SSO-policy gate.
  • Video call and recording quality — frozen video, echo, buffer stalls, and the video.recording.degraded QC verdict.
  • Video echo and codec mismatch — distorted, delayed, or looping audio with clean packet metrics — acoustic echo, broken device DSP, capture-pipeline fights, and relay-path variance.
  • Video avatar agent and render errors — the VIDEO_AVATAR_AGENT_* and VIDEO_AVATAR_RENDER_* 4xx family on the persona registry and the async render surface: the code-by-code decoder, the queued → rendering → completed / failed state machine with its per-verb matrix, the retrieve-and-reconcile retry pattern, and the escalation bundle.
  • Guest chat specific: Why did my guest’s video chat message bounce with 403 VIDEO_CHAT_GUEST_FORBIDDEN? — the invite-token identity resolution and lobby-admission gate a guest chat send must pass. Its siblings — why a guest sees no chat surface (the embed ships no chat panel; guest chat is the POST /api/v1/video/rooms/:id/chat API) and the room’s chat content policy on guests — sit beside it in the FAQ.
DNC, consent receipts, destination blocks, and the strict-sender-id FQDN gate.
  • 401 REAUTH_REQUIRED on destructive operations — the re-auth challenge gate on workspace deletion, GDPR erasure, HIPAA disable, force-transfer, and the 2FA verbs: mint endpoint by verb, header shape, expiry, single-use, and the binding-key reject.
  • Messaging pre-send gates — route a rejected send to the hard gate that fired: CONTACT_BLOCKED, QUIET_HOURS_BLOCKED / TCPA_QUIET_HOURS, OUTSIDE_SESSION_WINDOW, MESSAGING_NUMBER_DEACTIVATED.
  • DNC pre-flight returns 403 — DNC_SYNC_NOT_ENABLED on a send gate.
  • CONSENT_RECEIPT_INVALID — a caller receipt the API cannot verify.
  • BYOK key unavailable / decryption failed — BYOK_KEY_UNAVAILABLE 409 and DECRYPTION_FAILED 502 on a customer-managed-key-enforced field-encryption call.
  • SMS destination blocks — the spending and destination gate for SMS.
  • Strict sender-ID FQDN gate — SENDER_INVALID_FOR_DESTINATION when strict mode rejects a custom sender.
  • Mexico NOM-184 consent gate 422s — MESSAGING_MX_NOM184_CONSENT_MISSING when promotional MX SMS lacks recorded NOM-184 consent.
  • Türkiye SMS with a URL arrives stripped or empty — the BTK URL-strip gate: the tr_url_strip_warning metadata advisory and the older MESSAGING_TR_URL_STRIP_VIOLATION 422.
  • Fraud Shield blocked — FRAUD_SHIELD_BLOCKED 403s from your tenant-configured fraud rules.
  • Fraud review triage — work one alert end to end: the list, acknowledge/dismiss, and the export loop.
  • Compliance endpoint permissions: the role matrix — one table of which workspace role (owner/admin/developer/viewer/billing) each high-traffic compliance endpoint’s reads and writes need, how to read a 403 INSUFFICIENT_PERMISSIONS, the agents:read/agents:write scope-versus-role split, and where your own failed call is recorded.
  • Emergency stop — the org-wide outbound halt an owner/admin activates to freeze every dispatch path.
  • Sends blocked by the reassigned-number gate — MESSAGING_RND_REASSIGNED 422s on US SMS/MMS: the tenant-enabled RND scrub refusing a recycled number, the /compliance/rnd/check confirm path, the consent-evidence fixes, the posture toggle, and why blind retries never clear it.
  • RMD filing deficient or expired — FCC Robocall Mitigation Database lifecycle failures.
  • HIPAA blocked until the BAA is executed — the 403 on PUT /settings/hipaa while the BAA is pending.
  • PHI audience requires a BAA — HIPAA_BAA_REQUIRED 422 on a campaign launch.
  • Erasure request owns the contact — CONTACT_ERASURE_PENDING 422 on a send and ERASURE_COOLING_OFF_ACTIVE on a duplicate filing while a GDPR Article-17 request is pending.
  • Suppression scope mismatch — imported opt-outs still receive messages (or are over-blocked) because the per-row scope your CSV recorded differs from the one you intended.
  • Archival channel enablement — the freeze a contact enters on the archived lifecycle stage (blocks future sends until an explicit unarchive: true re-stage) plus the 409 ARCHIVAL_CHANNEL_NOT_ENABLED when a legal-hold / archival export targets a channel the archival policy does not include (or archival was never enabled); read the policy, enable the channel via PUT /compliance/archival, then re-dispatch.
  • Data-residency error family (RESIDENCY_*) — the four codes on the pin/lock/unlock surface: RESIDENCY_NOT_FOUND (unpin-then-unlock — bootstrap the config with PUT first), RESIDENCY_NOT_ENFORCED (lock without an enforced pin — set enforced: true first), RESIDENCY_REGION_UNAVAILABLE (enforcing a preview region — read the catalog’s availability, pin advisory-only or open a platform-provisioning ticket), and RESIDENCY_LOCKED (region-change on a frozen pin — deliberate unlock, then re-pin).
  • Crypto-envelope failures (ENCRYPTION_FAILED / DECRYPTION_FAILED) — the write-side ENCRYPTION_FAILED 5xx (transient — retry once) and the read-side 502 DECRYPTION_FAILED from a stale enc:v1 ciphertext during platform master-key rotation; self-recovering once the rotation settles, with the escalation bundle for a 502 that persists.
  • Opt-out list label conflicts — the 409 OPT_OUT_LIST_LABEL_CONFLICT on POST/PATCH of a messaging opt-out list: the label is unique among your tenant’s active lists, so resolve the collision (rename, or soft-delete the holder) and re-send once — the deterministic gate never clears on a blind retry.
  • Quiet-hours false positives — a send blocked during what the recipient reports as allowed hours: isolate which of the three false-block layers fired (campaign fallback window, org channel gate, TCPA voice rails), route to the owning tenant knob, and file the federal-rail misfire as a platform defect rather than weakening the one non-toggleable gate.
  • KYC submissions and documents — rejected uploads, sends refused on verification, profiles stuck in review, carrier document requests, 10DLC brand rejections, and documents that age out: diagnose the gate that held your submission and re-submit once the blocker is resolved.
Supersede and ordering semantics for webhook deliveries: how to apply a later event without letting it overwrite an earlier one.
Use the pages below together when a delivery stops reaching your handler: an endpoint that never saves, a verifier that keeps returning 401, DLQ’d deliveries you need to recover, or a flood of duplicate deliveries while you iterate. Start with the page that matches your symptom, not with the signature runbook by default:
  • Webhook endpoint creation errors — shape and permission errors when registering an endpoint.
  • Endpoint cap and DNS pre-create gates — the deterministic 422 pair: tenant endpoint quota reached, and a hostname that does not resolve at create time.
  • Signature verification (fail open vs fail closed) — raw-body parsing, key-rotation headers, and clock skew: the difference between a router that silently accepts unsigned deliveries and one that returns 401 on every failed check.
  • DLQ and recovery — retries, DLQ, and replay for deliveries that exhausted the attempt budget.
  • Webhook ordering and dedup — consumer-side dedup of repeated deliveries, keyed on the stable event id.
  • Webhook lifecycle error codes — which lifecycle state each webhook error code fires in, and the fix for WEBHOOK_DELIVERY_FAILED, WEBHOOK_PROCESSING_FAILED, and WEBHOOK_SIGNATURE_INVALID.
  • Webhook signature invalid — the end-to-end WEBHOOK_SIGNATURE_INVALID runbook: reproduce the HMAC mismatch locally, isolate wrong-secret / raw-body / middleware causes, read the delivery log, and recover with the retry semantics.
  • Integration webhook receiver returns 503 — the HubSpot / Salesforce / Calendly / Intercom / DIDWW receivers that fail closed with WEBHOOK_DISABLED, WEBHOOK_NOT_PROVISIONED, or WEBHOOK_SECRET_NOT_CONFIGURED when the signing secret is unprovisioned, and the per-integration recovery for each.
Dedup never means reprocessing a signature-failed message. Verification runs first — a delivery with a failing signature rejects with 401 and is never dedup-keyed, retried, or replayed into your handler. Fix the verifier fail-closed; do not ack and queue the payload for later.
OTP sends and checks, the TOTP/push/passkey/backup-code factor suite, and the push-notification token ladder.
  • Verify OTP — a send or a check that fails.
  • Verify factor suite — TOTP, push, passkey, and backup codes.
  • Verify binding gates — the BINDING_REQUIRED / BINDING_MISMATCH 422s on send or check.
  • Push token expiry — APNs 410, FCM UNREGISTERED, and Web Push endpoint retirements; capability-flag preflight; user_ids registration drift; and VAPID rotation.
  • Push broadcast pre-send gates — BROADCAST_TOO_LARGE (422 audience cap) and CHANNEL_RATE_LIMITED (429 per-channel velocity) on the wildcard (user_ids: ["*"]) surface; fix the gate, re-send once.
  • KBA caller-verification session errors — the seven KBA codes (KBA_SESSION_NOT_FOUND, KBA_SESSION_NOT_ACTIVE, KBA_CONTACT_NOT_FOUND, KBA_NO_CONTACT_LINKED, KBA_INSUFFICIENT_PROFILE_DATA, KBA_LOCKED, KBA_VERIFICATION_REQUIRED): the pending → verified/failed state machine, restart-vs-lookup fixes, and which sensitive endpoints gate on the verified session.
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.
  • Email test-recipient not verified — the 422 EMAIL_TEST_RECIPIENT_NOT_VERIFIED on a shared-sender send with no verified domain of your own: the recipient allowlist (saved contact, verified org member, legacy verified address), and the verify-your-domain exit that removes the gate for that sender entirely.
  • Inbound email never routes — parse domain match rules and trigger issues.
Spend caps, insufficient balance, and billing-pause blocks on outbound.
  • Spend-cap refusals — daily caps per channel.
  • Subaccount budget refusals — the two subaccount-scoped 402s (SUBACCOUNT_CHANNEL_BUDGET_EXCEEDED, SUBACCOUNT_MONTHLY_SPEND_CAP_EXCEEDED): which parent-set budget fired, how to read the subaccount’s live usage, and raising the budget versus waiting for the monthly reset.
  • Automatic security pause after unusual spend activity — the “…is temporarily suspended by an automatic security pause after unusual spend activity” refusal on voice or a messaging channel: the spend-velocity mitigation that wrote it, the self-serve clear on the fraud-mitigations surface, and the split from spend caps and insufficient balance.
  • INSUFFICIENT_BALANCE — the 402 that blocks a send when credits cannot cover it.
  • Billing recovery codes — the generic 402 ladder behind INSUFFICIENT_BALANCE: PAYMENT_REQUIRED, INSUFFICIENT_FUNDS, and the auto-top-up pair AUTO_TOPUP_PAYMENT_FAILED / AUTO_TOPUP_MONTHLY_CAP_REACHED.
  • Billing-gate outbound blocks — recovery from the pause block.
  • Pricing-gate errors — the PRICING_* family: decode the gate, split tenant-owned override fixes (PRICING_RATE_BELOW_WHOLESALE_COST, PRICING_OVERRIDE_SLOT_CONFLICT) from operator-owned FX and rate-card failures, and resolve with one named fix.
  • Send-price and country gates — the two pre-send 422s that look alike on the wire: MAX_PRICE_EXCEEDED (the per-send max_price ceiling on the messaging payload) and COUNTRY_NOT_ALLOWED (the org-wide country allowlist). Decode the envelope, then fix at claim time: raise or drop max_price, open allow-all or add the ISO code to the allowlist.
  • Pay-by-link reachability — the 422 NO_REACHABLE_CHANNEL when the recipient has no SMS-capable or email-capable (or voice) path for the hosted-checkout link; add a reachable channel to the contact before minting. Cross-surface page (ring-group cycles and the archival channel gate are the other two sections).
Squad daily and per-conversation LLM cost caps, agent runtime errors, and orchestration gates.
  • Squad and conversation cost caps — SQUAD_DAILY_CAP_REACHED / CONVERSATION_COST_CAP_REACHED 429s on the squad envelope: read the ceiling, raise or reset it, and deflect to a fallback queue.
  • Agent runtime errors — AGENT_ERROR, AGENT_NOT_CONFIGURED, AGENT_RESPONSE_INVALID, AGENT_EXECUTION_TIMEOUT, INVALID_MODEL, and LLM_PROVIDER_ERROR.
  • Promotion gate blocked a version — the fail-closed 422s on agent-version promotion: PROMOTION_GATE_FAILED (the pinned eval suite regressed) and RED_TEAM_GATE_FAILED (the safety floor or an adversarial-probe baseline broke); read the gate report, fix the failing golden sets or red-team categories, and re-promote.
  • AI guardrail refusals and cap blocks — the 403 SAFETY_CLASSIFIER_REFUSAL on prompt assist and trait auto-derive (revise the payload, never loop the retry), and the 422 AGENT_CHANNEL_CAP_EXCEEDED on assignment (read the cap, free a slot, raise it, or spread the load).
Vertical-bundle activation duplicates, stuck go-live checklists, version-frozen activations, and dashboard sign-in locks.
  • Vertical-bundle activation duplicates — duplicate draft profiles, a checklist that will not clear, and an activation pinned to an old bundle version.
  • ACCOUNT_LOCKED at dashboard sign-in — the 403 login lock: brute-force lockout, owner/admin freeze, or suspicious-login hold, and the unlock paths for each.
  • Password rejected during password reset — the 422 the reset form returns when the submitted password is on a known-breach list or fails the baseline rules: why that is a validation rejection rather than an outage, and how to pick a password that passes.
  • Support access (view-as) token failures — SESSION_REVOKED, TOKEN_ALREADY_USED, MISSING_COOKIE, and INVALID_TOKEN on the time-boxed support link you grant from Settings → Security, plus the tenant-side revoke controls.
  • SAML SSO and SCIM setup failures — the setup-time misconfiguration family: certificate/ACS 401s, PEM whitespace/header-strip, SHA-1 vs SHA-256 mismatch, clock-skew vs NotBefore/NotOnOrAfter, non-owner 403 writes on /api/v1/settings/saml, and SCIM orgSlug/Bearer mismatches.
  • Tenant provisioning lifecycle — the four tenant-lifecycle codes — MISSING_TENANT (400), TENANT_NOT_FOUND (404), TENANT_PROVISIONING (503), and TENANT_SCHEMA_INCOMPLETE (503) — with the 503-vs-404 split and the route to each fix.
  • DOMAIN_NOT_FOUND on the branded console — the 404 the public host→workspace lookup returns when a host is not a registered, active branded domain: the pending → verifying → active lifecycle, and the only-three-cases checklist for a host that was once resolved.
Auth and IP allowlists, schema readiness, rate limits, and import/flow failures.
Inbound SMS/RCS/WhatsApp route misses, RCS undelivered, Telegram, Slack OAuth redemption and token failures, the APAC channels (LINE, KakaoTalk, WeChat, Zalo), and Apple Messages for Business onboarding and send failures.
Caller-ID verification rejects and STIR/SHAKEN posture checks on the numbers you present.
  • Caller-ID verification rejects — VERIFICATION_REJECTED, CHALLENGE_INVALID, INVALID_CALLER_ID, and ALREADY_VERIFIED across the register → confirm flow.
  • Caller-ID FAQ entries — how long a pending verification row is bounded for, what a mistyped code burns (CHALLENGE_INVALID vs VERIFICATION_REJECTED), and whether a number verified on another tenant registers here (ALREADY_VERIFIED).
AI auto-suggest failures on the Segments empty-state panel, and the maker-checker refuses on approved audience activations.
  • Segment auto-suggest failures (AI_SUGGEST_FAILED) — the 502 on POST /segments/auto-suggest: split it from the parse and unavailable siblings, retry the transient class once, steer with focus_hint, and never loop the retry.
  • Activation approval state errors — the ACTIVATION_APPROVAL_* family on the maker-checker activation flow: NOT_FOUND, NOT_ACTIONABLE, ALREADY_DECIDED, SELF_DECISION, BATCH_CHANGED, and MISMATCH, with the re-enumerate, re-mint, or re-route move for each and the escalation payload.
  • Empty-audience campaign refusals (EMPTY_AUDIENCE_NOT_ALLOWED) — the 422 on campaign create against a zero-member segment or list: preview the matched count, respect the segment refresh cadence, expand the audience, then create.
Dispatch governance skips, expired signed landing links, first-response-wins submission semantics, and survey webhook silence.
  • Survey dispatch, signed links, and frequency-cap skips — decode the skippedRecent / skippedFatigue partition when the dispatch count falls short of the audience, tell a mangled landing token from an expired one, understand why a re-submission updates rather than duplicates a response, and bind the four live survey.* webhook events.
Runbooks for the signed-HMAC CDP ingest surface — the 401 signature gate past, and the event-level 422s your workspace’s own contracts fire.
  • Tracking-plan violations (TRACKING_PLAN_VIOLATION) — the 422 a tenant-owned tracking plan in enforcement=strict returns: decode details.violations to the fired rule (missing required, type/enum mismatch, extra property), decide between fixing the producer, amending the plan, or dropping to soft, and why no retry passes a tenant-owned policy gate.
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_QUARANTINED outcome.
  • DSAR export retry — requeue when a data-subject export fails.
  • Interactions list and CSV export — the flat 403 on the export for viewer roles, duplicate/skipped rows while paging, and filter quirks on the unified Interactions list.
  • Glossary links that 404 — a published internal link into the public glossary names a slug the registry does not ship; the three offender shapes (never-published slug, rename without re-pointing the link, invalid slug pattern) and the pre-publish slug-diff checklist.
  • QR code render failures — the four failure classes across /qr/generate|whatsapp|sms: undialable phone (400), the pseudo-scheme payload policy (400), malformed query parts (422), and the single retry-safe 502 QR_RENDER_FAILED.
Most API failures arrive as a structured envelope, not a runbook title — the code on the error body tells you which bucket it falls in and what to do next.
  1. Read error.code off the JSON envelope (and error.details for the field-level hint).
  2. If the code maps to one of the runbooks above, jump there — that is the fast path.
  3. If the code is not on this page, fall back to the class table below and follow the retry-safety guidance for its bucket.
The Error Code Reference is the fallthrough for any code without a dedicated runbook — do not treat it as the dead end.

​
Where error codes fit in

When the failure is a specific code 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. This hub is grouped by the surface each runbook works on — voice, messaging, video, compliance, channels, and the rest. When a new runbook ships, file it under the accordion that matches its surface so the index stays complete. For a failure that does not map to one of the runbooks, open a ticket with the steps you tried, the code from the API envelope when present, and the output of the endpoint you hit.