Common Issues

Field	Value
Document ID	ASCEND-HELP-002
Version	2026.04
Last Updated	April 2026
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

tip

Check the ASCEND status page and verify your API key is active before debugging further. Expired or revoked keys are the most common cause of authentication failures.

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: 2026.04 | Last Updated: April 2026