links.arjun.tv/docs/end-user/troubleshooting-decision-trees

Troubleshooting Decision Trees

Use these trees to quickly identify and resolve common issues based on the symptom you observe.

Click a branch to jump from symptom category to concrete API checks and remediation actions.

Link redirect fails

Link redirect fails
├─ Status 404?
│  ├─ Is the slug correct? → Check for typos in the URL path
│  ├─ Was the link just created? → Wait 1-2 minutes for propagation
│  └─ Is the domain correct? → Verify handle subdomain or custom domain
├─ Status 301/302 but wrong destination?
│  ├─ Are personalization rules active? → Check rules at /v2/handles/{handle}/personalization-rules
│  └─ Is a campaign overriding routing? → Check campaign status
├─ Status 503?
│  ├─ Check system health → GET /v2/system/health
│  └─ Is this a custom domain? → Verify domain reconciliation completed
└─ No response / timeout?
   ├─ Is the destination URL reachable? → Run link health check
   └─ DNS issue? → Verify DNS records for custom domain

Authentication fails

Authentication fails
├─ Status 401 missing_bearer_token?
│  └─ Add Authorization: Bearer {token} header
├─ Status 401 invalid_token?
│  ├─ Using JWT? → Re-login to get a fresh session
│  └─ Using PAT? → Verify format is patv1_{tokenId}.{secret}
├─ Status 401 token_expired?
│  ├─ JWT? → Re-login
│  └─ PAT? → Check if token was revoked or expired
├─ Status 401 expired_magic_link?
│  └─ Request a new magic link (valid 15 minutes, single-use)
└─ Status 403 insufficient_role?
   ├─ What role do you have? → GET /v2/handles/{handle}/collaborators
   ├─ Need OPERATOR? → Ask handle owner to upgrade your role
   └─ Need OWNER? → Only handle owner can perform this action

Feature or quota blocked

Feature or quota blocked
├─ Status 403 feature_locked?
│  ├─ Which feature? → Check the "feature" field in the error response
│  ├─ growth_tools? → Requires PRO plan (PAT tokens)
│  ├─ exports? → Requires PRO plan (link/analytics exports)
│  └─ Creator pages / Stripe? → Requires PRO plan
├─ Status 429 rate_limited?
│  ├─ Check your plan → GET /v2/billing/summary
│  ├─ FREE plan: 2 writes/day
│  ├─ PRO plan: 10 writes/day
│  └─ ENTERPRISE plan: 500 writes/day
└─ Upgrade plan → POST /v2/billing/checkout-session

Analytics data missing or unexpected

Analytics data missing or unexpected
├─ No data at all?
│  ├─ Was the link just created? → Wait up to 60 minutes for first rollup
│  ├─ Freshness status STALE? → Analytics pipeline may be lagging
│  └─ Check system health → GET /v2/system/health (redirect_analytics_freshness)
├─ Clicks lower than expected?
│  ├─ Check bot ratio → Query with ?confidence=true
│  └─ Ad blockers or privacy tools may prevent tracking
├─ Conversions lower than clicks?
│  ├─ ctx token expired? → Default 15-minute window after redirect
│  ├─ Conversion posted without ctx? → Attribution cannot be matched
│  └─ Idempotency deduplication? → Same idempotencyKey only counts once
├─ Country/device breakdown unavailable?
│  └─ Dimension rollups are forward-only from rollout date
└─ Export returns 403?
   └─ Requires PRO or ENTERPRISE plan (exports feature gate)

Domain setup issues

Domain setup issues
├─ Domain stuck in PENDING?
│  ├─ DNS records applied? → Verify CNAME or A records at your DNS provider
│  ├─ Run reconcile → POST /v2/account/domains/{domain}/reconcile
│  └─ Still pending? → DNS propagation can take up to 48 hours
├─ Domain returns wrong content?
│  ├─ Routes configured? → Check /v2/account/domains/{domain}/routes
│  └─ Handle assigned? → Verify domain-to-handle mapping
└─ SSL certificate error?
   └─ Reconcile triggers certificate provisioning — wait and retry

Visitor access issues

Visitor access issues
├─ Cannot access paid page after purchase?
│  ├─ Visitor session active? → Check cookie (_10x_visitor, 30-day TTL)
│  ├─ Purchase completed? → GET /v2/visitor/access
│  ├─ Refund issued? → Refund revokes access
│  └─ Different email? → Entitlement is tied to the email used at checkout
├─ Checkout fails?
│  ├─ Status 409 connect_not_configured? → Creator must connect Stripe first
│  ├─ Status 409 page_not_paid? → Page access mode must be PAID
│  └─ Status 401 visitor_unauthorized? → Visitor must authenticate first
├─ Magic link not received?
│  ├─ Check spam folder
│  ├─ Correct email address? → Re-submit magic link request
│  └─ Rate limited? → Wait and retry
└─ Group buy interest not recorded?
   ├─ Visitor authenticated? → Session cookie required
   └─ Group buy still accepting interest? → Check status is PUBLISHED

Webhook delivery fails

Webhook delivery fails
├─ Never received?
│  ├─ Subscription enabled? → GET /v2/handles/{handle}/webhooks
│  ├─ Event type subscribed? → Check eventTypes array includes the event
│  └─ Endpoint reachable? → Send a test delivery
├─ Signature verification fails?
│  ├─ Using correct secret? → Secret shown only at creation time
│  └─ Verify HMAC-SHA256: sha256=HMAC(secret, raw_body)
├─ Getting terminal_failure alerts?
│  └─ All 5 retries failed → Fix endpoint and re-enable subscription
└─ Delayed delivery?
   └─ Retries use exponential backoff: 5s, 10s, 20s, 40s, 80s

Related: