API Errors

Field	Value
Document ID	ASCEND-API-003
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: Intermediate

Overview

ASCEND uses consistent error codes and formats to help you diagnose and resolve issues. All errors include a unique request ID for support escalation.

Error Response Format

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "key_prefix": "owkai_admin_abc...",
      "reason": "key_expired"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-12-15T10:30:00Z"
  }
}

Authentication Errors (4xx)

Code	HTTP	Description	Resolution
INVALID_API_KEY	401	API key not found	Verify key is correct
EXPIRED_API_KEY	401	API key expired	Generate new key
REVOKED_API_KEY	401	API key revoked	Contact admin
INVALID_TOKEN	401	JWT invalid	Re-authenticate
EXPIRED_TOKEN	401	JWT expired	Refresh token
MFA_REQUIRED	401	MFA not completed	Complete MFA flow
ACCOUNT_LOCKED	403	Account locked	Wait or contact admin
INSUFFICIENT_PERMISSIONS	403	Role not authorized	Request access

Example: Invalid API Key

{
  "status": "error",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "key_prefix": "owkai_admin_abc..."
    }
  }
}

Resolution:

# Test your key by listing API keys
curl "https://pilot.owkai.app/api/keys/list" \
  -H "X-API-Key: owkai_admin_..."

Validation Errors (400/422)

Code	HTTP	Description	Resolution
MISSING_REQUIRED_FIELD	400	Required field missing	Add field
INVALID_FIELD_VALUE	400	Invalid value	Check format
VALIDATION_ERROR	422	Schema validation failed	Review schema
INVALID_JSON	400	Malformed JSON	Fix JSON syntax

Example: Missing Required Field

{
  "status": "error",
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field 'agent_id' is missing",
    "details": {
      "field": "agent_id",
      "requirement": "required",
      "type": "string"
    }
  }
}

Resource Errors (404/409)

Code	HTTP	Description	Resolution
RESOURCE_NOT_FOUND	404	Resource doesn't exist	Check ID
AGENT_NOT_FOUND	404	Agent not registered	Register agent
ACTION_NOT_FOUND	404	Action ID invalid	Verify ID
RESOURCE_CONFLICT	409	Duplicate resource	Use existing
AGENT_ALREADY_EXISTS	409	Agent ID taken	Use unique ID

Example: Agent Not Found

{
  "status": "error",
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent 'trading-bot-001' is not registered",
    "details": {
      "agent_id": "trading-bot-001",
      "suggestion": "Register agent before submitting actions"
    }
  }
}

Resolution:

# Register the agent first
curl -X POST "https://pilot.owkai.app/api/registry/agents" \
  -H "X-API-Key: owkai_..." \
  -d '{"agent_id": "trading-bot-001", "agent_type": "trading"}'

Rate Limiting Errors (429)

Code	HTTP	Description	Resolution
RATE_LIMIT_EXCEEDED	429	Too many requests	Wait and retry
QUOTA_EXCEEDED	429	Monthly quota hit	Upgrade plan

Example: Rate Limited

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 60 seconds",
    "details": {
      "limit": 100,
      "window": "1m",
      "current": 105,
      "retry_after": 60
    }
  }
}

Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1702656060
Retry-After: 60

Resolution:

import time

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

Governance Errors (4xx)

Code	HTTP	Description	Resolution
ACTION_DENIED	403	Policy denied action	Review policy
APPROVAL_REQUIRED	202	Needs human approval	Wait for approval
KILL_SWITCH_ACTIVE	403	Agent killed	Reactivate agent
POLICY_VIOLATION	403	Rule violation	Modify request

Example: Action Denied

{
  "status": "error",
  "error": {
    "code": "ACTION_DENIED",
    "message": "Action denied by policy 'no-sensitive-data-access'",
    "details": {
      "policy_id": "pol_xyz789",
      "policy_name": "no-sensitive-data-access",
      "risk_score": 95,
      "risk_level": "critical",
      "reason": "Access to sensitive data prohibited"
    }
  }
}

Server Errors (5xx)

Code	HTTP	Description	Resolution
INTERNAL_ERROR	500	Server error	Retry later
SERVICE_UNAVAILABLE	503	Maintenance	Check status
GATEWAY_TIMEOUT	504	Timeout	Retry
DATABASE_ERROR	500	DB issue	Contact support

Example: Server Error

{
  "status": "error",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred. Please try again later.",
    "details": {
      "request_id": "req_xyz789"
    }
  }
}

Resolution:

1. Note the request_id
2. Check status.owkai.app
3. Retry with exponential backoff
4. Contact support if persistent

Error Handling Best Practices

1. Check Error Codes

response = client.submit_action(...)

if response.status_code != 200:
    error = response.json().get('error', {})
    code = error.get('code')

    if code == 'RATE_LIMIT_EXCEEDED':
        handle_rate_limit(response)
    elif code == 'APPROVAL_REQUIRED':
        handle_pending_approval(response)
    elif code == 'INVALID_API_KEY':
        refresh_api_key()

2. Implement Retries

import time
from functools import wraps

def retry_on_error(max_retries=3, backoff_factor=2):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_retries):
                try:
                    return func(*args, **kwargs)
                except RateLimitError as e:
                    if attempt < max_retries - 1:
                        time.sleep(backoff_factor ** attempt)
                    else:
                        raise
        return wrapper
    return decorator

3. Log Request IDs

import logging

logger = logging.getLogger(__name__)

response = client.submit_action(...)
request_id = response.headers.get('X-Request-ID')

if response.status_code >= 400:
    logger.error(f"API error: {response.json()}, request_id: {request_id}")

Support Escalation

When contacting support, include:

1. Request ID - From error response or headers
2. Error Code - e.g., INVALID_API_KEY
3. Timestamp - When error occurred
4. Request Details - Endpoint, method, relevant parameters

Support Ticket Template:
- Request ID: req_xyz789
- Error Code: INTERNAL_ERROR
- Timestamp: 2025-12-15T10:30:00Z
- Endpoint: POST /api/v1/actions
- Steps to Reproduce: ...

Next Steps

• Troubleshooting - Issue resolution
• API Overview - API conventions
• Rate Limits - Limit details

---

Document Version: 1.0.0 | Last Updated: December 2025