OpenAnalyst Product Docs

Quickly identify and resolve common issues based on the symptom you observe.

Troubleshooting Decision Trees

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

Top-level troubleshooting map for redirects, auth, quota, analytics, domain, visitor and webhook issues.RedirectCheck slug/domain correctness, propagation timing, destination health, and system health endpoint.AuthenticationMap 401/403 code to JWT, PAT, or role failures and refresh or rotate credentials.Feature and quotaUse feature field + billing summary to identify plan gate or write quota exhaustion.AnalyticsEvaluate rollup freshness, bot-confidence filters, context token expiry, and idempotency dedupe.DomainInspect DNS records, reconcile state, and certificate provisioning lag before escalation.
Click a branch to jump from symptom category to concrete API checks and remediation actions.
  1. Classify symptom
  2. Run first API checks
  3. Escalate with evidence
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?
│  └─ Delivery reached terminal classification → Fix endpoint first, then retest or replay with evidence
└─ Delayed delivery?
   └─ Retryable failures wait 5s, 10s, 20s, and 40s between attempts

Related: