Troubleshooting and Support

Use this guide when login, routing, domain, or analytics flows fail.

Triage checklist

Reproduce once and capture the full URL.
Confirm handle, slug, and domain values.
Confirm auth mode (JWT, PAT, or visitor flow).
Capture the HTTP status code and error code from the response body.
Check the common error reference below.
If unresolved, submit a support report with request context.

Common error reference

Status	Error code	Meaning	Next step
400	`invalid_*`	Request body or parameter is malformed	Check the field named in the error code
401	`missing_bearer_token`	No Authorization header sent	Add `Authorization: Bearer {token}`
401	`invalid_token`	Token format is unrecognized	Verify token is a valid JWT or PAT
401	`token_expired`	JWT or PAT has expired	Re-authenticate or generate a new token
401	`expired_magic_link`	Magic link older than 15 minutes	Request a new magic link
401	`used_magic_link`	Magic link already consumed	Request a new magic link
403	`insufficient_role`	Your role lacks permission for this action	Ask the handle owner to upgrade your role
403	`insufficient_scope`	PAT token missing required scope	Create a new PAT with the needed scope
403	`feature_locked`	Feature requires a higher plan	See Plans, Quotas, and Feature Gates
404	`not_found`	Resource does not exist	Verify handle, slug, or ID values
404	`handle_not_found`	Handle does not exist	Check for typos in the handle name
409	`connect_not_configured`	Stripe Connect not set up for this handle	Complete Stripe Connect onboarding
410	`file_expired`	File has passed its expiry date	Upload a new file if needed
429	`rate_limited`	Daily write quota or rate limit exceeded	Wait and retry, or upgrade your plan

Escalation and support

Submitting a support report

POST /v2/support/report

{
  "handle": "acme",
  "summary": "Redirect returns 404 for slug 'launch'",
  "details": "Slug was created 10 minutes ago. Public URL returns 404.",
  "sessionId": "optional_browser_session_id",
  "requestId": "optional_api_request_id"
}

Include as much context as possible: the handle, slug, error code, and any request/session IDs.

Operator escalation

For urgent issues, operators can submit an escalation:

POST /v2/operator/escalations

{
  "handle": "acme",
  "severity": "HIGH",
  "summary": "All redirects returning 503 for handle acme"
}

Severity levels: LOW, MEDIUM, HIGH. Escalations trigger owner alerts and are logged to the audit trail.

Content reports (public)

Anyone can report abusive content without authentication:

POST /v2/public/content-report

{
  "handle": "suspicious-handle",
  "reason": "phishing",
  "details": "Link redirects to a credential harvesting page.",
  "reporterEmail": "reporter@example.com"
}

Rate limit: 5 reports per IP per hour.

SLA reference

Area	Target	Notes
Analytics freshness	Under 60 minutes	CloudFront logs to dashboard
System health checks	15-minute staleness threshold	Alerts if data is older than 15 minutes
Link health check timeout	4 seconds	HEAD/GET request to destination URL
Webhook delivery attempts	5 retries with exponential backoff	5s, 10s, 20s, 40s, 80s
Magic link validity	15 minutes	Single-use
Visitor session duration	30 days	Cookie-based
Audit event retention	90 days	Automatic TTL cleanup

Health checks

System health

GET /v2/system/health

Returns the status of platform subsystems:

usage_meters_connectivity — database connectivity
redirect_analytics_freshness — analytics pipeline lag
targeting_profile_freshness — targeting profile projection lag
targeting_rollup_freshness — segment rollup pipeline lag

Each check returns PASS, FAIL, or UNKNOWN with a severity of INFO, WARN, or CRITICAL.

Link health

POST /v2/handles/{handle}/links/health-check

Validates that destination URLs are reachable. Returns HTTP status codes for each link checked.

Audit trail

GET /v2/handles/{handle}/audit-events

Returns the most recent audit events for a handle (default 50, max 100). Requires OPERATOR role or above, or a PAT with system.audit.read scope.

Use the audit trail to:

Verify who made a configuration change and when.
Trace billing, collaborator, or link modification events.
Provide incident context in support reports.

API fallback

POST /v2/support/report
POST /v2/operator/escalations
POST /v2/public/content-report
GET /v2/system/health
GET /v2/handles/{handle}/audit-events
POST /v2/handles/{handle}/links/health-check