> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting hub
> Every troubleshooting page in one place — a sectioned index of all runbook pages under the Reference group.
## Nota de idioma
Cuando no hay traducción disponible, se muestra el contenido en inglés como fallback. Conserva los códigos de error, las rutas de API y los bloques de código.
# 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](/reference/troubleshooting) 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](/troubleshooting/message-queued) owns the
other pre-send holds — `scheduled`, `pending`, and quiet-hours. Every other
runbook lives under `/troubleshooting/`. Webhook failures split two
ways as well: the [Webhook delivery failures](#webhook-delivery-failures)
accordion below owns endpoint creation, signature verification, DLQ
recovery, and dedup, while the [Webhooks](#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](/troubleshooting/inbox-assignment-and-auto-close) —
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](/troubleshooting/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](/troubleshooting/attachment-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.
Decode a degraded provider tile on **Settings → Presence** — what each
badge means, what caused it, and the exact fix.
* [Presence federation degraded states](/troubleshooting/presence-federation-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](/reference/troubleshooting) — the owner of
`queued` as its own state: full cause table, escalation path, status
decoder.
* [Message parked before sending](/troubleshooting/message-queued) —
the matrix for the other pre-send holds: `scheduled`, `pending`, and
quiet-hours.
* [A scheduled message that never fired](/troubleshooting/scheduled-send-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](/troubleshooting/submitted-no-receipt) —
the row reached `sent` but a `delivered`/`undelivered` outcome never lands.
* [Recover a failed or late DLR](/troubleshooting/failed-dlr-recovery) —
retry and backfill a missing delivery receipt.
* [Message undelivered or failed](/troubleshooting/message-undelivered-failed) —
a terminal non-delivered outcome and what to do next.
* [Campaign and journey enrollment errors](/troubleshooting/campaign-journey-errors) —
`AUDIENCE_TOO_LARGE`, `JOURNEY_VALIDATION_FAILED`, and `RESUME_FAILED`.
* [Campaign and conference state-machine transition errors](/troubleshooting/campaign-conference-state-machine) —
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](/troubleshooting/fan-out-and-upload-errors) —
`EMAIL_SEND_FAILED_ALL`, `ALL_CHANNELS_FAILED`, and file-upload rejections.
* [Media upload failed](/troubleshooting/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](/troubleshooting/channel-unavailable-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](/troubleshooting/validation-gates) — 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](/troubleshooting/channel-and-conversation-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](/troubleshooting/template-variant-missing) —
the 422 `NO_VARIANT_FOR_CHANNEL` send gate.
* [Fallback chain names a channel with no variant](/troubleshooting/template-fallback-variant-missing) —
the authoring-time `VALIDATION_ERROR` on `fallback_chain`.
* [Sender resolution and pool errors](/troubleshooting/sender-resolution-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](/troubleshooting/sender-pool-empty) —
`SENDER_POOL_EMPTY`: the pool exists but has no members to draw from.
* [Pool spread and anti-snowshoe alerts](/troubleshooting/sender-pool-spread-alerts) —
pool spread too thin or volume that outgrew the pool.
* [Inbound SMS not recording](/troubleshooting/inbound-sms-not-recording) —
inbound MO messages or DLRs that never reach your tenant.
* [SMPP bind rejects and command\_status codes](/troubleshooting/smpp-bind-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.
Buy numbers, get sender IDs approved, work warming caps, and handle India DLT
or 10DLC gates.
* [Number purchase failure](/troubleshooting/numbers-provisioning-failed) —
inventory races and provisioning retries.
* [Connectivity SIM events](/troubleshooting/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](/troubleshooting/bulk-purchase-carrier-rate-limit) —
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](/troubleshooting/port-out-blocked) —
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](/troubleshooting/number-warming-caps) —
`DAILY_CAP_EXCEEDED`, `WARMING_QUOTA_EXCEEDED`, and `NUMBER_MPS_EXCEEDED`.
* [Sender ID rejected before send](/troubleshooting/sender-id-not-registered) —
the pre-send `SENDER_ID_NOT_REGISTERED`/`SENDER_ID_NOT_APPROVED` gate.
* [Numeric sender owned by someone else](/troubleshooting/sender-ownership-blocked) —
the `422 SENDER_NOT_OWNED` cross-org ownership gate and its fail-closed
503 sibling.
* [Number masking and proxy-session failures](/troubleshooting/number-masking-proxy-session) —
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](/troubleshooting/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](/troubleshooting/number-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](/troubleshooting/sender-warmup-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](/troubleshooting/sender-id-registration-resubmit) —
resubmit or reactivate a declined sender.
* [India DLT gate](/troubleshooting/in-dlt-gates) — a 422 with a
`dlt_template_id`/`dlt_entity_id` requirement.
* [10DLC campaign rejected](/troubleshooting/10dlc-campaign-rejection) —
resubmit a campaign the carrier declined.
* [10DLC not registered](/troubleshooting/ten-dlc-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](/troubleshooting/toll-free-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](/troubleshooting/sender-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](/troubleshooting/sip-trunk) — registration, health, failover,
and capacity.
* [Voice call quality](/troubleshooting/voice-call-quality) — one-way audio,
dead air, jitter, and PDD.
* [Voice-model credential rejected](/troubleshooting/voice-provider-credential-rejected) —
the `422 VOICE_CREDENTIAL_PROVIDER_REJECTED` on registering or rotating a
BYO TTS/STT provider key.
* [Secure-payment capture failures](/troubleshooting/secure-payment-capture) —
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](/troubleshooting/voice-payment-mandate-confirmations) —
`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](/troubleshooting/supervisor-takeover-failures) —
the `SUPERVISOR_*` 500s, the already-active-takeover 409, and the
`supervisor.takeover_failed` webhook.
* [In-call AI handoff, deflection, and follow-up failures](/troubleshooting/voice-ai-handoff-deflect-followup) —
`HANDOFF_FAILED`, `DEFLECTION_FAILED`, and `FOLLOWUP_SEND_FAILED` on the
three in-call AI exit lanes.
* [Voice call park orbit](/troubleshooting/voice-call-park) —
`PARK_SLOTS_FULL`, `PARK_SLOT_OCCUPIED`, and `PARK_ALREADY_RETRIEVED`.
* [MCID flag failures](/troubleshooting/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](/troubleshooting/conference-failures) —
rooms stuck open, legs that drop, and missing end reasons.
* [Call flip and call pickup](/troubleshooting/conference-flip-pickup) —
`FLIP_*` handoff rejects and `PICKUP_*` claim-race rejects.
* [Dialer modes not advancing](/troubleshooting/dialer-preview) — preview,
power, and predictive campaigns that stop pulling contacts.
* [TCPA blocked calls](/troubleshooting/tcpa-window-blocked-calls) — the
dialing window a blocked call fell outside.
* [State mini-TCPA blocked calls](/troubleshooting/tcpa-state-mini-tcpa-window-blocked-calls) —
`TCPA_STATE_DIALING_WINDOW_BLOCKED` on per-state dialing overlays.
* [FCC AI-voice consent gate](/troubleshooting/fcc-ai-voice-blocked-calls) —
`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](/troubleshooting/voice-pre-send-gate-chain) —
read the pre-send screen verdict, separate hard fails from warns, and
re-submit.
* [TCPA voice-guard sentinel breadcrumbs](/troubleshooting/voice-window-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](/troubleshooting/voice-destination-blocks) —
destination and emergency blocks.
* [Ring-group chain cycles](/troubleshooting/routing-and-channel-misconfig) —
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](/troubleshooting/stir-shaken-attestation-downgrade) —
spam-likely labels, delegate certificates, and branded-calling overrides.
* [STIR/SHAKEN never measured](/troubleshooting/stir-shaken-not-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](/troubleshooting/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](/troubleshooting/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](/troubleshooting/queue-sla-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](/troubleshooting/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](/troubleshooting/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](/troubleshooting/transcription-and-synthetic-voice-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.
* [Agent outbound-call and voice-clone guard codes](/troubleshooting/agent-outbound-guards) —
the pre-origination agent toggle 409 (`OUTBOUND_CALLING_DISABLED`), the
reserved `GUARDRAIL_VIOLATION` triage, and the `VOICE_CLONE_CONSENT_REQUIRED`
422 gate.
* [Failover and failback](/troubleshooting/media-planes-failover-or-failback) —
a call that fails right after a regional move.
* [VOICE\_GATEWAY\_ERROR at call-send](/troubleshooting/voice-gateway-error) —
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](/troubleshooting/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](/troubleshooting/video-room-lifecycle) —
join-token refusals, capacity 400s, lobby gating, and agent dispatch errors.
* [Video room features: chat, polls, Q\&A, invites, RTMP](/troubleshooting/video-features-chat-polls-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](/troubleshooting/video-call-quality) —
frozen video, echo, buffer stalls, and the `video.recording.degraded` QC
verdict.
* [Video echo and codec mismatch](/troubleshooting/video-echo-codec) —
distorted, delayed, or looping audio with clean packet metrics — acoustic
echo, broken device DSP, capture-pipeline fights, and relay-path variance.
DNC, consent receipts, destination blocks, and the strict-sender-id FQDN
gate.
* [401 REAUTH\_REQUIRED on destructive operations](/troubleshooting/reauth-challenge-flow) —
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](/troubleshooting/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](/troubleshooting/dnc-check-gated) —
`DNC_SYNC_NOT_ENABLED` on a send gate.
* [CONSENT\_RECEIPT\_INVALID](/troubleshooting/consent-receipt-invalid) — a
caller receipt the API cannot verify.
* [BYOK key unavailable / decryption failed](/troubleshooting/byok-key-unavailable) —
`BYOK_KEY_UNAVAILABLE` 409 and `DECRYPTION_FAILED` 502 on a
customer-managed-key-enforced field-encryption call.
* [SMS destination blocks](/troubleshooting/sms-destination-blocks) — the
spending and destination gate for SMS.
* [Strict sender-ID FQDN gate](/troubleshooting/strict-sender-id-invalid-destination) —
`SENDER_INVALID_FOR_DESTINATION` when strict mode rejects a custom sender.
* [Mexico NOM-184 consent gate 422s](/troubleshooting/mx-nom184-consent) —
`MESSAGING_MX_NOM184_CONSENT_MISSING` when promotional MX SMS lacks
recorded NOM-184 consent.
* [Türkiye SMS with a URL arrives stripped or empty](/troubleshooting/turkiye-url-strip) —
the BTK URL-strip gate: the `tr_url_strip_warning` metadata advisory and the
older `MESSAGING_TR_URL_STRIP_VIOLATION` 422.
* [Fraud Shield blocked](/troubleshooting/fraud-shield-blocked) —
`FRAUD_SHIELD_BLOCKED` 403s from your tenant-configured fraud rules.
* [Fraud review triage](/compliance/fraud-review-triage) — work one alert
end to end: the list, acknowledge/dismiss, and the export loop.
* [Compliance endpoint permissions: the role matrix](/troubleshooting/compliance-endpoint-permissions) —
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](/compliance/emergency-stop) — the org-wide outbound halt
an owner/admin activates to freeze every dispatch path.
* [RMD filing deficient or expired](/troubleshooting/rmd-filing-deficiency-or-expired) —
FCC Robocall Mitigation Database lifecycle failures.
* [HIPAA blocked until the BAA is executed](/troubleshooting/hipaa-enable-baa-not-executed) —
the 403 on `PUT /settings/hipaa` while the BAA is pending.
* [PHI audience requires a BAA](/troubleshooting/phi-audience-baa-required) —
`HIPAA_BAA_REQUIRED` 422 on a campaign launch.
* [Erasure request owns the contact](/troubleshooting/pending-compliance-and-erasure-gates) —
`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](/troubleshooting/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](/troubleshooting/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\_\*)](/troubleshooting/data-residency-errors) —
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)](/troubleshooting/encryption-envelope-failures) —
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](/troubleshooting/opt-out-list-label-conflict) —
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](/troubleshooting/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.
Supersede and ordering semantics for webhook deliveries: how to apply a
later event without letting it overwrite an earlier one.
* [Webhook ordering and fan-out](/troubleshooting/webhook-ordering-fanout) —
supersede on `created_at` so a later event never rewrites 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](/troubleshooting/webhook-endpoint-creation) —
shape and permission errors when registering an endpoint.
* [Endpoint cap and DNS pre-create gates](/troubleshooting/webhook-endpoint-cap-and-dns-pre-create) —
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)](/webhooks/troubleshooting-signature-failures) —
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](/troubleshooting/webhook-deliveries) — retries, DLQ,
and replay for deliveries that exhausted the attempt budget.
* [Webhook ordering and dedup](/troubleshooting/webhook-event-dedup) —
consumer-side dedup of repeated deliveries, keyed on the stable event id.
* [Webhook lifecycle error codes](/troubleshooting/webhook-lifecycle-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](/troubleshooting/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](/troubleshooting/integration-webhook-receiver-disabled) —
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](/troubleshooting/verify-otp) — a send or a check that fails.
* [Verify factor suite](/troubleshooting/verify-factor-suite) — TOTP, push,
passkey, and backup codes.
* [Verify binding gates](/troubleshooting/verify-binding-gates) — the
`BINDING_REQUIRED` / `BINDING_MISMATCH` 422s on send or check.
* [Push token expiry](/troubleshooting/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](/troubleshooting/push-broadcast-caps) —
`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](/troubleshooting/kba-caller-verification) —
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](/troubleshooting/email-bounces-complaints) —
reputation and suppression follow-ups.
* [Email DNS drift](/troubleshooting/email-dns-drift) — verification drift
and recovery.
* [Email test-recipient not verified](/troubleshooting/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](/guides/inbound-email-troubleshooting) — parse
domain match rules and trigger issues.
Spend caps, insufficient balance, and billing-pause blocks on outbound.
* [Spend-cap refusals](/troubleshooting/spend-caps-hit) — daily caps per
channel.
* [INSUFFICIENT\_BALANCE](/troubleshooting/insufficient-balance) — the 402
that blocks a send when credits cannot cover it.
* [Billing recovery codes](/troubleshooting/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](/troubleshooting/billing-pause-block-recovery) —
recovery from the pause block.
* [Pricing-gate errors](/troubleshooting/pricing-gates) — 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](/troubleshooting/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](/troubleshooting/routing-and-channel-misconfig) —
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](/troubleshooting/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](/troubleshooting/agent-errors) — `AGENT_ERROR`,
`AGENT_NOT_CONFIGURED`, `AGENT_RESPONSE_INVALID`,
`AGENT_EXECUTION_TIMEOUT`, `INVALID_MODEL`, and `LLM_PROVIDER_ERROR`.
* [Promotion gate blocked a version](/troubleshooting/agent-promotion-gate-blocks) —
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.
Vertical-bundle activation duplicates, stuck go-live checklists,
version-frozen activations, and dashboard sign-in locks.
* [Vertical-bundle activation duplicates](/troubleshooting/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](/troubleshooting/account-locked-login) —
the 403 login lock: brute-force lockout, owner/admin freeze, or
suspicious-login hold, and the unlock paths for each.
* [Support access (view-as) token failures](/troubleshooting/support-access-impersonation) —
`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](/troubleshooting/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](/troubleshooting/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](/troubleshooting/resolve-domain-not-found) —
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.
* [Authentication and IP allowlist](/troubleshooting/auth-and-api-keys) —
key mode and IP-allowlist failures.
* [TURNSTILE\_REQUIRED (422) on public form endpoints](/troubleshooting/turnstile-required) —
the public marketing-lead capture and DSA-request-portal bot gate: Cloudflare
Turnstile token missing, replayed past its single-use window, site-key
mismatch, or a visitor-network bot flag.
* [API\_HOST\_RETIRED (410)](/troubleshooting/retired-api-host-410) — the
retired pre-cutover API host's guard: migrate the SDK base URL, proxy
upstream, or env var to the canonical `api.orbit.devotel.io`.
* [Agent runtime errors](/troubleshooting/agent-errors) — `AGENT_ERROR`,
`AGENT_NOT_CONFIGURED`, `AGENT_RESPONSE_INVALID`, `AGENT_EXECUTION_TIMEOUT`,
`INVALID_MODEL`, and `LLM_PROVIDER_ERROR`.
* [Agent Studio graph and custom-tool validation](/troubleshooting/agent-graph-and-custom-tools) —
the publish/register validation family: `GRAPH_VALIDATION_FAILED`,
`GRAPH_TOOL_NODES_NOT_SUPPORTED_IN_TEST_RUN`, `RESERVED_TOOL_NAME`,
`TOOL_NAME_TAKEN`, `TOOL_DISABLED`, `INVALID_EXECUTOR_URL`,
`TOOL_IMPL_NOT_REGISTERED`, `INVALID_HANDOFF_TARGETS`,
`INVALID_KNOWLEDGE_BASE_IDS`, and `LEGACY_KB_DOC_NOT_RECHUNKABLE`.
* [LLM timeouts and upstream failures](/troubleshooting/llm-upstream-failures) —
the model-call failure family: `LLM_TIMEOUT` (504) and
`LLM_UPSTREAM_ERROR` (502) on agent runs, plus the conversational-IVR
NLU codes `IVR_CLASSIFY_LLM_ERROR` / `IVR_SLOT_EXTRACT_LLM_ERROR` (503);
per-code retry policy and when to escalate with the request id.
* [Keyword rules: the matching model](/concepts/keyword-rules-model) — the
dispatch model behind inbound auto-reply, opt-in/opt-out, agent hand-off,
and flow triggers: match types, creation-order precedence, and why at
most one rule fires on a message.
* [Prompt-regression blocks an agent-version rollback](/troubleshooting/agent-prompt-regression-registered) —
the gate that withholds approval on a prompt rollback until the eval run
clears.
* [A2A federation discovery and peer tasks](/troubleshooting/a2a-federation) —
`A2A_DISCOVERY_DISABLED` 422s, unsigned/unverifiable HMAC envelopes
(`X-A2A-Signature`), `A2A_PEER_ERROR` on outbound delegation, and peer
registrations refused by the public-FQDN check.
* [MCP server registration rejected](/troubleshooting/mcp-server-registration) —
the `INVALID_MCP_SERVER_URL` / `INVALID_MCP_OAUTH_TOKEN_URL` SSRF-guard
422s and `MCP_SERVER_NAME_CONFLICT` 409s.
* [Orby operator errors](/troubleshooting/orby-operator-errors) — the
`ORBY_SESSION_*` token failures, `ORBY_TOOL_*` authorization gates, turn
limits (`ORBY_RATE_LIMITED`, `ORBY_ITERATION_LIMIT`, `ORBY_TURN_FAILED`,
`ORBY_LLM_FAILED`), KB readiness (`ORBY_KB_*`), and
`ORBY_THREAD_NOT_OWNED`.
* [Orby pending-action approval](/troubleshooting/orby-tool-approval) — the
`PENDING_ACTION_*` 409s on the approve/reject card: state, race, expiry,
and the fail-closed persist 500.
* [Action approvals: the human-in-the-loop gate](/concepts/action-approvals-model) —
the dispatch model behind the approval card: which tool calls propose
instead of execute, and how a proposal moves from pending to approved,
rejected, or expired.
* [Tenant schema incomplete](/troubleshooting/tenant-schema-incomplete-503) —
the 503 that gates a route while the schema finishes.
* [Custom domain not found on the branded console](/troubleshooting/domain-not-found-branded-resolve) —
`DOMAIN_NOT_FOUND` 404s on the public host lookups: unclaimed or
not-yet-active domain, CNAME drift, and the neutral-theme fallback.
* [Dashboard error fallback](/troubleshooting/dashboard-error-fallback) — the
"Something went wrong" / "A newer version is available" wall and what to
send support.
* [Rate limits and cool-downs](/troubleshooting/rate-limits) — 429 cooldown
recovery.
* [Platform sheds load with 503 UNDER\_PRESSURE](/troubleshooting/platform-load-shed-503) —
the event-loop-saturated 503, the `UNDER_PRESSURE` vs
`SERVICE_UNAVAILABLE` split, and the retry posture.
* [Import jobs](/troubleshooting/import-jobs) — an import that fails or
stalls.
* [Flow executions failed](/troubleshooting/flow-executions-failed) — a flow
whose execution returned an error.
* [Idempotency and billing gates](/troubleshooting/idempotency-and-billing-gates) —
`IDEMPOTENCY_KEY_REQUIRED`, `DEDUCT_IN_FLIGHT`, and auto-top-up alerts.
* [Recording integrity, legal hold, and QC](/troubleshooting/recording-integrity-and-legal-hold) —
seal/verify/export-digest failures, legal-hold 500s, QC stuck or
rejected, and consent gates.
Inbound SMS/RCS/WhatsApp route misses, RCS undelivered, Telegram, and the
APAC channels (LINE, KakaoTalk, WeChat, Zalo).
* [Inbound SMS no route](/troubleshooting/inbound-sms-no-route) — inbound
to your number never arrives.
* [Inbound LINE, Kakao, WeChat, Zalo no route](/troubleshooting/apac-channel-inbound-no-route) —
the four-channel APAC inbound matrix.
* [Inbound WhatsApp or RCS no route](/troubleshooting/inbound-channels-no-route) —
an inbound message with no route assignment.
* [Viber inbound and routing errors](/troubleshooting/viber-inbound-and-route-failures) —
the Tier 1 SMPP vs Tier 2 Business-API split: inbound MO never arriving,
outbound stuck in `queued`/`undelivered`, and the routing error codes.
* [RCS undelivered](/troubleshooting/rcs-undelivered) — a message that never
reached an RCS-capable device.
* [RCS brand not approved](/troubleshooting/rcs-brand-not-approved) — a bot
submit or verification that 409s under a held brand; reading
`details.brand_status` and the resubmit loop.
* [WhatsApp Business Calling pre-flight gates](/troubleshooting/whatsapp-calling-gates) —
country blocklist, recipient permission, wallet pre-flight, daily cap,
and the shared-WABA resolver, plus call-control and initiation codes.
* [USSD menu, callback, and simulate](/troubleshooting/ussd-menu-callback) —
the graceful `END Service is not available.` close, the engine `END
Service unavailable.` route fault, and the `PUT /ussd/menu` 422 invariant
checks.
* [Telegram channel errors](/troubleshooting/telegram-connect) — connect,
push, and mutual-hand-off errors.
* [WhatsApp connection and re-authentication](/troubleshooting/whatsapp-connection) —
`NOT_CONNECTED` vs `CONNECTION_INVALID`, tier limits, and quality pauses.
* [WhatsApp campaign auto-paused on a RED quality rating](/troubleshooting/whatsapp-quality-red-campaign-pause) —
reading `WHATSAPP_QUALITY_RED`, telling Meta's auto-pause from an
operator pause, and recovering the rating in Meta Business Manager.
* [WhatsApp sends blocked by a billing failure](/troubleshooting/whatsapp-billing-issue) —
`WHATSAPP_BILLING_ISSUE` (Meta 131042): fix the WABA payment method in
Meta Business Manager, then re-send once.
* [WhatsApp templates pending, rejected, or blocked](/troubleshooting/whatsapp-template) —
pending review, rejection reasons, and 24h-window errors.
* [WhatsApp 24-hour session expired](/troubleshooting/whatsapp-session-expired) —
`WHATSAPP_SESSION_EXPIRED` on a free-form send: check the window, fall
back to an approved template, and re-engage.
* [WhatsApp template variable count mismatch](/troubleshooting/whatsapp-template-var-count) —
the send-side pre-flight on `template_params` count vs `{{N}}` placeholders.
* [Wallet pass lifecycle: generation and void](/troubleshooting/wallet-pass-lifecycle) —
the three lifecycle edges a pass moves through (`active`, `voided`,
`expired`): why `generation` drifts between clients, why update-after-void
returns `409 CONFLICT` while duplicate-issue returns a 200 replay, why the
highest observed `generation` is canonical, and how to cache-bust a
deep-link that still opens the old pass.
* [WhatsApp Flow submissions](/troubleshooting/whatsapp-flow-submissions) —
flows with no submissions, empty lists, or recipients who cannot open one.
* [WhatsApp Flows API 502 META\_API\_ERROR](/troubleshooting/whatsapp-flows-meta-api-error) —
the classified 502 on the Flows list/create proxy endpoints: decode the
envelope to the upstream cause, split retry-with-Idempotency-Key from
reconnect-the-WABA, and stay under Meta's per-WABA call budget.
* [WhatsApp migration stuck](/troubleshooting/whatsapp-migration) — unstick a
WABA migration: verification, eligibility, template sync, and webhooks.
* [LINE inbound webhook setup](/troubleshooting/line-webhook-setup) — the LINE
Developers Console URL gate and tenant resolution by channel id.
* [KakaoTalk template gates](/troubleshooting/kakao-template-gates) — the
Alimtalk/Friendtalk 422 `VALIDATION_ERROR` content gates.
* [WeChat and Zalo credential precedence](/troubleshooting/wechat-zalo-credentials) —
`CHANNEL_NOT_CONFIGURED` and the per-org vs platform-default resolution
chain.
* [WhatsApp re-authentication and Embedded Sign-up recovery](/troubleshooting/whatsapp-auth-and-connection-recovery) —
token-exchange vs selection errors on the connect flow, an expired stored
token, business-verification gates, the WABA-linked-elsewhere conflict,
and the back-to-green verify.
* [SMPP credential provisioning unavailable](/troubleshooting/smpp-credential-provisioning-unavailable) —
the 503 `SMPP_BACKEND_UNAVAILABLE` on SMPP credential issuance and
rotation when the tenant schema, the organization encryption key, or the
reconciler queue is down — the control-plane failure before any bind is
possible.
* [Messenger/Instagram 24-hour window closed](/troubleshooting/messenger-window-closed) —
the 422 `MESSAGING_WINDOW_CLOSED` gate and the tag / fallback ways out.
* [Messenger channel not connected](/troubleshooting/messenger-not-connected) —
the 409 `MESSENGER_NOT_CONNECTED` refusal on persona reads/writes, the
`MESSENGER_TOKEN_UNREADABLE` sibling, and the not-configured family the
envelope routes by `details.channel_id`.
* [CRM integration sync error codes](/troubleshooting/crm-integration-errors) —
decode `CRM_CONNECTION_MISSING`, `CRM_AUTH_EXPIRED`, and `CRM_DISPATCH_FAILED`
on Salesforce / HubSpot / CDP sync legs, reconnect once, and stop the
un-decoded dispatch retry loop.
* [Fax send failures](/troubleshooting/fax-send-failures) — the four classes:
422 content/destination rejects at POST time, the carrier passthrough
diagnostic on `message.failed`, the transient 502, and the held-at-`sent`
never-delivered row, plus the on-success billing rule.
Caller-ID verification rejects and STIR/SHAKEN posture checks on the
numbers you present.
* [Caller-ID verification rejects](/troubleshooting/verifications-rejects) —
`VERIFICATION_REJECTED`, `CHALLENGE_INVALID`, `INVALID_CALLER_ID`, and
`ALREADY_VERIFIED` across the register → confirm flow.
AI auto-suggest failures on the Segments empty-state panel.
* [Segment auto-suggest failures (`AI_SUGGEST_FAILED`)](/troubleshooting/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.
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`)](/troubleshooting/tracking-plan-violations) —
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](/troubleshooting/agent-eval-queue) — an eval
that stalls or fails to start.
* [Conversation merge refused](/troubleshooting/conversation-merge) —
`WEAK_IDENTITY_MATCH_REQUIRES_CONFIRMATION`.
* [Co-browse stuck](/troubleshooting/cobrowse-stuck) — a session that never
hands off.
* [Suspicious or empty queue](/troubleshooting/enqueued-empty-states) — an
order or import stuck in an enqueued state.
* [Quarantined media file](/troubleshooting/file-scan-quarantined) — the
`FILE_SCAN_QUARANTINED` outcome.
* [DSAR export retry](/troubleshooting/dsar-export-failures) — requeue when
a data-subject export fails.
* [Interactions list and CSV export](/troubleshooting/interactions-list.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](/troubleshooting/glossary-link-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.
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.
| Class | Retry-safety | Where to check next |
| - | - | - |
| Tenant-owned pre-send reject (403/422 gate) | Retry only after fixing the payload or tenant config. | Look in the send-gate/compliance sections above. |
| Transient 429 / 5xx | Retriable — honor `details.retry_after` seconds, otherwise exponential backoff. | [Rate limits and cool-downs](/troubleshooting/rate-limits) |
| Deterministic 422 validation | Never retry — fix the payload first. | Inspect `error.details` for the exact field. |
| Unknown / unclassified code | Treat as a transient 5xx and open a ticket with `meta.request_id`. | [Error Code Reference](/reference/error-codes) |
The [Error Code Reference](/reference/error-codes) 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](/reference/error-codes) 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.