Troubleshooting Overview

Field	Value
Document ID	ASCEND-HELP-004
Version	1.0.0
Last Updated	December 19, 2025
Author	Ascend Engineering Team
Publisher	OW-KAI Technologies Inc.
Classification	Enterprise Client Documentation
Compliance	SOC 2 CC6.1/CC6.2, PCI-DSS 7.1/8.3, HIPAA 164.312, NIST 800-53 AC-2/SI-4

Reading Time: 5 minutes | Skill Level: All Levels

Overview

This guide helps you diagnose and resolve common issues with ASCEND. Use the diagnostic tools, check error codes, and follow the resolution steps for each issue type.

Quick Diagnostics

Check System Health

curl "https://pilot.owkai.app/api/diagnostics/health" \
  -H "Authorization: Bearer <admin_jwt>"

Health Score Interpretation

Score	Status	Action
90-100	Healthy	No action needed
80-89	Warning	Monitor closely
60-79	Degraded	Investigate components
0-59	Critical	Immediate attention

Common Issues

Authentication Errors

Error Code	Message	Cause	Solution
AUTH_001	Invalid API key	Key not found or expired	Generate new API key
AUTH_002	Token expired	JWT session timeout	Re-authenticate
AUTH_003	MFA required	MFA not completed	Complete MFA verification
AUTH_004	Account locked	Too many failed attempts	Wait for lockout period

API Key Issues

# Verify API key status
curl "https://pilot.owkai.app/api/keys/verify" \
  -H "X-API-Key: owkai_admin_..."

Common Causes:

• Key expired (check expires_at)
• Key revoked by admin
• Incorrect key format
• Rate limit exceeded

Resolution:

# Generate new key if needed
curl -X POST "https://pilot.owkai.app/api/keys/generate" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{"name": "Replacement Key", "role": "admin"}'

Action Submission Errors

Error Code	Message	Cause	Solution
ACT_001	Agent not registered	Unknown agent_id	Register agent first
ACT_002	Missing required field	Incomplete request	Check required fields
ACT_003	Invalid action type	Unknown action_type	Use valid action type
ACT_004	Risk score too high	Auto-denied by policy	Request manual review

Rate Limiting

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests",
  "retry_after": 60,
  "limit": "100/minute",
  "current": 105
}

Resolution:

• Implement exponential backoff
• Cache responses where appropriate
• Batch requests when possible
• Contact support for limit increase

Multi-Tenancy Issues

Symptom	Cause	Solution
Data not found	Wrong organization context	Verify org_id in JWT
Access denied	Cross-tenant access attempt	Use correct credentials
Missing data	RLS policy active	Ensure org context set

Diagnostic Tools

API Health Check

curl "https://pilot.owkai.app/api/diagnostics/api" \
  -H "Authorization: Bearer <admin_jwt>"

Database Health Check

curl "https://pilot.owkai.app/api/diagnostics/database" \
  -H "Authorization: Bearer <admin_jwt>"

Integration Health Check

curl "https://pilot.owkai.app/api/diagnostics/integrations" \
  -H "Authorization: Bearer <admin_jwt>"

Error Response Format

All ASCEND errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable description",
  "code": "SPECIFIC_ERROR_CODE",
  "details": {
    "field": "additional context"
  },
  "request_id": "req_abc123",
  "timestamp": "2025-12-15T10:30:00Z"
}

Debug Mode

Enable Debug Logging (SDK)

from ascend import AscendClient

client = AscendClient(
    api_key="owkai_...",
    debug=True,
    log_level="DEBUG"
)

View Request/Response

# Enable request logging
client.enable_request_logging()

# Submit action with debug info
result = client.submit_action(...)
print(f"Request ID: {result.request_id}")
print(f"Response Time: {result.response_time_ms}ms")

Support Escalation

Before Contacting Support

1. Collect information:

   • Request ID / Correlation ID
   • Error code and message
   • Timestamp of issue
   • Steps to reproduce

2. Run diagnostics:

   curl "https://pilot.owkai.app/api/diagnostics/health" \
     -H "Authorization: Bearer <admin_jwt>"

3. Check system status:

   • Visit status.owkai.app
   • Check for known incidents

Contact Support

Issue Severity	Channel	Response SLA
Critical (P1)	Phone + Email	15 minutes
High (P2)	Email + Portal	1 hour
Medium (P3)	Portal	4 hours
Low (P4)	Portal	24 hours

Support Portal

https://support.owkai.app

Required Information:
- Organization ID
- User email
- Request IDs
- Error messages
- Screenshots (if applicable)

Self-Service Resolution

Clear Browser Cache

For dashboard issues:

1. Clear browser cache and cookies
2. Hard refresh (Ctrl+Shift+R)
3. Try incognito/private mode

Reset API Key

# Revoke compromised key
curl -X DELETE "https://pilot.owkai.app/api/keys/{key_id}" \
  -H "Authorization: Bearer <admin_jwt>"

# Generate new key
curl -X POST "https://pilot.owkai.app/api/keys/generate" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{"name": "New Key", "role": "admin"}'

Force Session Refresh

# Logout and re-authenticate
curl -X POST "https://pilot.owkai.app/api/auth/logout" \
  -H "Authorization: Bearer <jwt_token>"

Next Steps

• Common Issues - Detailed solutions
• FAQ - Frequently asked questions
• API Errors - Error code reference

---

Document Version: 1.0.0 | Last Updated: December 2025