Troubleshooting Guide¶
Find solutions organized by problem type. Select the category that matches your issue for targeted troubleshooting steps.
Troubleshooting by Category¶
-
Platform Setup & Configuration
Account setup, data controller configuration, team management, and initial platform deployment.
- Data Controller Setup Issues - Organization profile and legal configuration
- Domain Verification Problems - SSL certificate and DNS configuration
- Team Access Management - User roles, permissions, and invitations
- Environment Configuration - Development, staging, and production setup
-
API & GraphQL Integration
Authentication, GraphQL queries, webhook delivery, and third-party service connectivity.
- Authentication Failures - JWT tokens, API keys, and PAT flow issues
- GraphQL Query Errors - Schema validation, permission errors, and syntax issues
- Webhook Delivery Problems - Signature validation, connectivity, and payload issues
- Rate Limiting & Throttling - API quota management and optimization
-
Third-Party Service Integration
Shopify, Stripe, Mailchimp, WooCommerce, and other platform connectors.
- E-commerce Platform Issues - Shopify, WooCommerce webhook and API synchronization
- Payment Processor Integration - Stripe transaction monitoring and compliance
- Marketing Platform Connectivity - Mailchimp, Klaviyo subscriber and preference sync
- Custom Integration Development - API wrapper and middleware implementation
-
Performance Optimization
Dashboard loading, API response times, database queries, and report generation.
- Dashboard Loading - Browser caching, network connectivity, browser compatibility
- API Response Times - Query optimization and pagination
- Report Generation - Date range optimization and large dataset handling
- Widget Performance - Consent widget loading and website integration
-
Security & Compliance
Compliance configuration, data breach response, and regulatory reporting.
- GDPR/CCPA Compliance Issues - Regulatory configuration and reporting
- Consent Collection - Consent widget issues and preference synchronization
- Rights Request Processing - Access, deletion, and portability request handling
-
Error Code Resolution
Error code reference with solutions and step-by-step resolution guidance.
- Platform Error Codes - Dxtra error code reference with solutions
- Integration Error Messages - Third-party service error interpretation
- Authentication Errors - Login, token, and permission error resolution
Common Questions¶
How do I reset my password?
- Go to the Dxtra Login Page
- Click "Forgot Password"
- Enter your registered email address
- Check your email for reset instructions
- Create a new secure password
Password Requirements
- Minimum 8 characters
- Include uppercase and lowercase letters
- Include numbers and special characters
Why can't I access my Dxtra Dashboard?
Common Causes & Solutions:
| Issue | Solution |
|---|---|
| Expired Session | Log out completely and log back in |
| Browser Cache | Clear cookies and cache for *.dxtra.ai |
| VPN/Firewall | Check corporate firewall allows *.dxtra.ai |
| Account Suspended | Contact support for account status |
How do I change my account email address?
- Go to Account Settings in your dashboard
- Click "Change Email Address"
- Enter your new email address
- Verify the new email via confirmation link
Important
The old email address will lose access immediately after verification.
Why are my API calls returning 401 Unauthorized?
Checklist:
- Valid API Key: Ensure your API key hasn't expired
- JWT Token: Exchange API key for JWT token first
- Correct Headers: Include
Authorization: Bearer <JWT>andX-Hasura-Role: user - Token Expiry: JWT tokens expire after 1 hour - refresh as needed
My webhooks aren't being received. What's wrong?
Webhook Debugging Steps:
- Check Webhook URL: Ensure it includes correct
didanddxKeyparameters - Verify HTTPS: Webhook endpoints must use HTTPS
- Test Connectivity: Use webhook testing tools to verify reachability
- Review Logs: Check your server logs for incoming requests
- Signature Validation: Ensure webhook signatures are being validated correctly
Webhook URL Format:
How do I troubleshoot GraphQL errors?
Typical GraphQL Error Response:
{
"errors": [
{
"message": "Field 'names' is not defined by type 'DataController'",
"locations": [{"line": 4, "column": 7}],
"path": ["dataControllers"]
}
]
}
Resolution Steps: 1. Check Field Names: Verify against GraphQL schema 2. Validate Permissions: Ensure role has required access 3. Review Query Structure: Check syntax and nesting 4. Consult API Docs: Reference field definitions
How do I configure my first Data Controller?
- Log into Dxtra Dashboard
- Create Data Controller
- Navigate to Settings > Data Controllers
- Click "Add Data Controller"
- Fill in organization details
- Configure Domain
- Add your website domains
- Verify domain ownership
- Invite Team Members
- Set up user roles and permissions
- Send invitation emails
- Complete Onboarding
- Review compliance settings
- Configure consent preferences
What integrations are available?
Currently Supported:
| Platform | Type | Status |
|---|---|---|
| Shopify | E-commerce | Active |
| Stripe | Payments | Active |
| Mailchimp | Marketing | Active |
| WooCommerce | E-commerce | Active |
| Klaviyo | Marketing | Active |
| Customer.io | Marketing | Active |
| Eventbrite | Events | Partial |
| SurveyMonkey | Surveys | Partial |
| QuickBooks | Accounting | Partial |
How does Dxtra help with GDPR compliance?
GDPR Compliance Features:
- Lawful Basis Tracking: Legal basis assignment and documentation
- Data Subject Rights: Processing of access, deletion, and portability requests
- Audit Trails: Processing activity records for Article 30 compliance
- Data Minimization: Collect and process only necessary data
- Breach Notification: DPA notification workflows
What about CCPA compliance?
CCPA Compliance Features:
- Right to Opt-Out: "Do Not Sell" implementation
- Right to Know: Data disclosure processes
- Right to Delete: Consumer data deletion workflows
- Non-Discrimination: Equal service regardless of privacy choices
Response Timeline Requirements: - Access Requests: 45 days maximum - Deletion Requests: 45 days maximum - Opt-Out Requests: 15 days maximum
Getting Help¶
Self-Service Resources¶
- Search Documentation: Use Ctrl+K to search across all documentation
- Error Code Reference: Check Error Messages for specific errors
- Integration Guides: Review service-specific guides for integration issues
Contact Support¶
If you cannot resolve an issue using self-service resources:
- Gather relevant information:
- Error messages (exact text)
- Screenshots of the issue
- Steps to reproduce
-
Browser and OS information
-
Contact support via email: support@dxtra.ai