Common Issues

Field	Value
Document ID	ASCEND-HELP-002
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: 10 minutes | Skill Level: All Levels

Authentication Issues

"Invalid API Key" Error

Symptoms:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}

Solutions:

1. Verify key format - Keys should start with owkai_

# Correct
X-API-Key: owkai_admin_abc123...

# Incorrect
X-API-Key: abc123...
Authorization: owkai_admin_abc123...

2. Check key status

curl "https://pilot.owkai.app/api/keys/verify" \
  -H "X-API-Key: owkai_..."

3. Generate new key if expired

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

"Token Expired" Error

Symptoms:

{
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "JWT token has expired"
  }
}

Solutions:

1. Refresh token

curl -X POST "https://pilot.owkai.app/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your_refresh_token"}'

2. Re-authenticate if refresh fails

curl -X POST "https://pilot.owkai.app/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@company.com", "password": "..."}'

MFA Issues

Problem: MFA code rejected

Solutions:

1. Check time sync - TOTP requires synchronized clocks
2. Wait for next code - Codes expire every 30 seconds
3. Use backup code if available
4. Contact admin to reset MFA

Agent Issues

"Agent Not Found" Error

Symptoms:

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent 'my-agent' is not registered"
  }
}

Solutions:

1. Register the agent first

curl -X POST "https://pilot.owkai.app/api/agents/register" \
  -H "X-API-Key: owkai_..." \
  -d '{
    "agent_id": "my-agent",
    "agent_type": "custom"
  }'

2. Check agent ID - IDs are case-sensitive

# Correct
"agent_id": "my-agent"

# Wrong (uppercase)
"agent_id": "My-Agent"

Agent "Killed" Status

Symptoms: Actions rejected with "Agent is killed"

Solutions:

1. Check agent status

curl "https://pilot.owkai.app/api/agents/my-agent" \
  -H "X-API-Key: owkai_..."

2. Reactivate if appropriate

curl -X POST "https://pilot.owkai.app/api/agents/my-agent/reactivate" \
  -H "Authorization: Bearer <admin_jwt>" \
  -d '{"reason": "Investigation complete"}'

Agent Health "Unhealthy"

Problem: Agent showing unhealthy status

Solutions:

1. Send heartbeat

curl -X POST "https://pilot.owkai.app/api/agents/my-agent/heartbeat" \
  -H "X-API-Key: owkai_..." \
  -d '{"status": "healthy"}'

2. Check heartbeat interval - Default is every 5 minutes
3. Review agent logs for errors

Action Issues

Actions Always Denied

Problem: All actions being denied

Check:

1. Risk score thresholds

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

2. Smart rules - May have overly broad deny rule

curl "https://pilot.owkai.app/api/smart-rules?action=DENY" \
  -H "Authorization: Bearer <admin_jwt>"

3. Agent trust level - Sandbox agents have limited auto-approve

Actions Stuck in "Pending"

Problem: Actions not being approved

Solutions:

1. Check approval queue

curl "https://pilot.owkai.app/api/governance/pending" \
  -H "Authorization: Bearer <jwt_token>"

2. Check approver availability - Ensure approvers are active

3. Check timeout settings

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

4. Configure escalation if approvers unavailable

High Latency on Actions

Problem: Action submission taking too long

Solutions:

1. Check system status

curl "https://pilot.owkai.app/api/health" \
  -H "X-API-Key: owkai_..."

2. Reduce payload size - Large parameters increase latency

3. Use async submission for non-blocking

result = client.submit_action(..., wait_for_approval=False)
# Poll for result later
status = client.get_action_status(result.action_id)

API Issues

Rate Limit Exceeded

Symptoms:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 45 seconds"
  }
}

Solutions:

1. Implement backoff

import time

if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)

2. Check current usage

curl "https://pilot.owkai.app/api/rate-limits/status" \
  -H "X-API-Key: owkai_..."

3. Use bulk operations when possible

Connection Timeout

Problem: Requests timing out

Solutions:

1. Increase timeout

import requests
response = requests.post(url, timeout=60)  # 60 seconds

2. Check network - Verify connectivity to pilot.owkai.app

3. Use regional endpoint if available

SSL Certificate Errors

Problem: SSL verification failing

Solutions:

1. Update CA certificates

pip install --upgrade certifi

2. Check system time - Certificate validation requires correct time

3. Don't disable SSL - Never use verify=False in production

Webhook Issues

Webhooks Not Receiving Events

Problem: Webhook endpoint not receiving notifications

Check:

1. Webhook status

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

2. Test webhook

curl -X POST "https://pilot.owkai.app/api/webhooks/{id}/test" \
  -H "Authorization: Bearer <admin_jwt>"

3. Check subscribed events - Ensure correct events subscribed

4. Check DLQ for failed deliveries

curl "https://pilot.owkai.app/api/webhooks/{id}/dlq" \
  -H "Authorization: Bearer <admin_jwt>"

Webhook Signature Validation Failing

Problem: HMAC signature doesn't match

Solutions:

1. Use raw request body - Don't parse before verification

# Correct
body = request.get_data()
signature = hmac.new(secret, body, sha256).hexdigest()

# Wrong
body = request.get_json()  # This modifies the body

2. Check secret - Ensure using correct webhook secret

3. Check encoding - Body should be UTF-8

SSO Issues

SAML Authentication Failing

Problem: SAML login not working

Check:

1. Certificate expiration

curl "https://pilot.owkai.app/api/sso/saml/company.com/status" \
  -H "Authorization: Bearer <admin_jwt>"

2. Clock skew - Servers must be time-synced

3. Attribute mapping - Ensure email attribute is mapped

Users Not Provisioned

Problem: SSO users can't access after login

Check:

1. JIT provisioning enabled

curl "https://pilot.owkai.app/api/sso/company.com/jit" \
  -H "Authorization: Bearer <admin_jwt>"

2. Default role configured

3. Domain allowlist - User domain must be allowed

Debugging Tools

Enable Debug Logging

# SDK
export ASCEND_LOG_LEVEL=DEBUG

# Python
import logging
logging.getLogger('ascend').setLevel(logging.DEBUG)

Get Request ID

Every response includes a request ID:

X-Request-ID: req_xyz789

Include this when contacting support.

Check System Status

curl "https://status.owkai.app/api/status"

Getting Help

If issues persist:

1. Gather information:

   • Request ID
   • Error message
   • Timestamp
   • Steps to reproduce

2. Check documentation:

   • FAQ
   • API Errors

3. Contact support:

   • Email: support@owkai.app
   • Portal: support.owkai.app

---

Document Version: 1.0.0 | Last Updated: December 2025