Error Codes

This guide covers all possible error codes, their meanings, and how to handle them in your Cortex integration.

🚨 Error Response Format

All Cortex errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "parameter": "specific_field",
      "expected": "expected_value",
      "provided": "actual_value"
    },
    "suggestion": "How to fix this error",
    "documentation": "https://docs.usecortex.co/api/errors#error-code"
  },
  "request_id": "req_error_123abc456def",
  "timestamp": "2025-01-09T15:30:00Z"
}

📋 HTTP Status Codes

Status	Category	Description
200	Success	Request completed successfully
400	Client Error	Invalid request parameters
401	Authentication	Invalid or missing API key
403	Authorization	Insufficient permissions
404	Not Found	Resource not found
429	Rate Limit	Too many requests
500	Server Error	Internal server error
502	Bad Gateway	Upstream service error
503	Service Unavailable	Service temporarily unavailable

🔑 Authentication Errors (401)

INVALID_API_KEY

{
  "code": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked"
}

Causes:

• API key is malformed
• API key has been revoked
• API key doesn't exist

Solutions:

• Verify API key format: cortex_sk_...
• Generate new API key in dashboard
• Check for extra spaces or characters

EXPIRED_API_KEY

{
  "code": "EXPIRED_API_KEY", 
  "message": "The API key has expired"
}

Solutions:

• Generate new API key
• Update payment method (if applicable)
• Contact support for account issues

MISSING_API_KEY

{
  "code": "MISSING_API_KEY",
  "message": "Authorization header is required"
}

Solutions:

• Add Authorization: Bearer YOUR_API_KEY header
• Or use X-API-Key: YOUR_API_KEY header

❌ Request Errors (400)

Query Validation

QUERY_REQUIRED

{
  "code": "QUERY_REQUIRED",
  "message": "Query parameter is required",
  "details": {
    "parameter": "query",
    "expected": "string (1-500 characters)",
    "provided": null
  }
}

QUERY_TOO_SHORT

{
  "code": "QUERY_TOO_SHORT",
  "message": "Query must be at least 1 character long"
}

QUERY_TOO_LONG

{
  "code": "QUERY_TOO_LONG",
  "message": "Query exceeds maximum length of 500 characters",
  "details": {
    "max_length": 500,
    "provided_length": 742
  }
}

Parameter Validation

INVALID_MAX_RESULTS

{
  "code": "INVALID_MAX_RESULTS",
  "message": "max_results must be between 1 and 20",
  "details": {
    "parameter": "max_results",
    "min_value": 1,
    "max_value": 20,
    "provided": 25
  }
}

INVALID_LANGUAGE

{
  "code": "INVALID_LANGUAGE",
  "message": "Unsupported language code",
  "details": {
    "parameter": "language",
    "provided": "xyz",
    "supported": ["en", "es", "fr", "de", "ja", "zh"]
  }
}

INVALID_COUNTRY

{
  "code": "INVALID_COUNTRY",
  "message": "Unsupported country code",
  "details": {
    "parameter": "country", 
    "provided": "xx",
    "format": "ISO 3166-1 alpha-2"
  }
}

INVALID_FORMAT

{
  "code": "INVALID_FORMAT",
  "message": "Unsupported response format",
  "details": {
    "parameter": "format",
    "provided": "xml",
    "supported": ["json", "markdown", "text", "html"]
  }
}

Content Errors

CONTENT_TOO_LARGE

{
  "code": "CONTENT_TOO_LARGE",
  "message": "Request content exceeds size limit",
  "details": {
    "max_size_mb": 10,
    "provided_size_mb": 15.7
  }
}

INVALID_JSON

{
  "code": "INVALID_JSON",
  "message": "Request body contains invalid JSON",
  "details": {
    "line": 5,
    "column": 12,
    "syntax_error": "Unexpected token '}'"
  }
}

🚫 Authorization Errors (403)

INSUFFICIENT_PERMISSIONS

{
  "code": "INSUFFICIENT_PERMISSIONS",
  "message": "API key does not have permission for this operation",
  "details": {
    "required_permission": "validate:advanced",
    "current_plan": "starter",
    "upgrade_url": "https://usecortex.co/pricing"
  }
}

FEATURE_NOT_AVAILABLE

{
  "code": "FEATURE_NOT_AVAILABLE",
  "message": "Feature not available on current plan",
  "details": {
    "feature": "batch_validation",
    "required_plan": "pro",
    "current_plan": "starter"
  }
}

⏱️ Rate Limiting Errors (429)

RATE_LIMITED

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded",
  "details": {
    "limit": 60,
    "period": "minute",
    "reset_time": "2025-01-09T15:31:00Z",
    "retry_after": 42
  }
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704812460
Retry-After: 42

MONTHLY_LIMIT_EXCEEDED

{
  "code": "MONTHLY_LIMIT_EXCEEDED",
  "message": "Monthly request limit exceeded",
  "details": {
    "monthly_limit": 2000,
    "requests_used": 2000,
    "reset_date": "2025-02-01T00:00:00Z",
    "upgrade_url": "https://usecortex.co/pricing"
  }
}

🔍 Processing Errors (422)

Search Errors

NO_RESULTS_FOUND

{
  "code": "NO_RESULTS_FOUND",
  "message": "No relevant results found for the query",
  "suggestion": "Try different keywords or broaden your search"
}

SEARCH_TIMEOUT

{
  "code": "SEARCH_TIMEOUT",
  "message": "Search request timed out",
  "details": {
    "timeout_seconds": 15,
    "suggestion": "Reduce max_results or try a more specific query"
  }
}

INSUFFICIENT_SOURCES

{
  "code": "INSUFFICIENT_SOURCES",
  "message": "Could not find enough reliable sources",
  "details": {
    "sources_found": 1,
    "sources_required": 2,
    "suggestion": "Broaden your search or provide specific sources"
  }
}

Extraction Errors

URL_INVALID

{
  "code": "URL_INVALID",
  "message": "The provided URL is not valid",
  "details": {
    "url": "invalid-url",
    "expected_format": "https://example.com/path"
  }
}

URL_UNREACHABLE

{
  "code": "URL_UNREACHABLE",
  "message": "Could not access the provided URL",
  "details": {
    "url": "https://example.com/missing",
    "http_status": 404,
    "suggestion": "Verify the URL is correct and accessible"
  }
}

EXTRACTION_FAILED

{
  "code": "EXTRACTION_FAILED",
  "message": "Could not extract content from the URL",
  "details": {
    "reason": "Content too dynamic or JavaScript-heavy",
    "suggestion": "Try a different URL or contact support"
  }
}

Validation Errors

CLAIM_TOO_VAGUE

{
  "code": "CLAIM_TOO_VAGUE",
  "message": "Claim is too vague to validate effectively",
  "suggestion": "Provide more specific details or context"
}

VALIDATION_TIMEOUT

{
  "code": "VALIDATION_TIMEOUT", 
  "message": "Validation process timed out",
  "details": {
    "sources_checked": 3,
    "sources_pending": 5,
    "suggestion": "Reduce scope or provide specific sources"
  }
}

🏥 Server Errors (5xx)

INTERNAL_SERVER_ERROR (500)

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An internal error occurred while processing your request",
  "details": {
    "incident_id": "inc_789xyz123",
    "suggestion": "Please try again or contact support if the issue persists"
  }
}

SERVICE_UNAVAILABLE (503)

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Service is temporarily unavailable",
  "details": {
    "estimated_recovery": "2025-01-09T16:00:00Z",
    "status_page": "https://status.usecortex.co"
  }
}

UPSTREAM_ERROR (502)

{
  "code": "UPSTREAM_ERROR",
  "message": "Error communicating with upstream services",
  "suggestion": "This is usually temporary, please try again"
}

🛠️ Error Handling Best Practices

Python Error Handling

from cortex import CortexClient, CortexError
import time

client = CortexClient(api_key="your_key")

def robust_search(query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search(query)
            
        except CortexError as e:
            if e.code == "RATE_LIMITED":
                # Exponential backoff
                wait_time = 2 ** attempt
                print(f"Rate limited, waiting {wait_time}s...")
                time.sleep(wait_time)
                continue
                
            elif e.code == "SEARCH_TIMEOUT":
                # Reduce complexity and retry
                if attempt < max_retries - 1:
                    query = query[:100]  # Shorten query
                    continue
                    
            elif e.code in ["QUERY_TOO_LONG", "QUERY_TOO_SHORT"]:
                # Query validation errors - don't retry
                raise e
                
            elif e.status_code >= 500:
                # Server errors - retry with backoff
                wait_time = 2 ** attempt
                time.sleep(wait_time)
                continue
                
            # Other errors - don't retry
            raise e
            
    raise Exception("Max retries exceeded")

# Usage
try:
    result = robust_search("AI developments")
    print(result.summary)
except CortexError as e:
    print(f"Error: {e.code} - {e.message}")
    if e.suggestion:
        print(f"Suggestion: {e.suggestion}")

JavaScript Error Handling

import Cortex, { CortexError } from '@cortex/sdk';

const cortex = new Cortex({ apiKey: 'your_key' });

async function robustSearch(query, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await cortex.search(query);
      
    } catch (error) {
      if (error instanceof CortexError) {
        switch (error.code) {
          case 'RATE_LIMITED':
            const waitTime = Math.pow(2, attempt) * 1000;
            console.log(`Rate limited, waiting ${waitTime}ms...`);
            await new Promise(resolve => setTimeout(resolve, waitTime));
            continue;
            
          case 'SEARCH_TIMEOUT':
            if (attempt < maxRetries - 1) {
              query = query.substring(0, 100); // Shorten query
              continue;
            }
            break;
            
          case 'QUERY_TOO_LONG':
          case 'QUERY_TOO_SHORT':
            // Don't retry validation errors
            throw error;
            
          default:
            if (error.statusCode >= 500) {
              // Retry server errors
              const waitTime = Math.pow(2, attempt) * 1000;
              await new Promise(resolve => setTimeout(resolve, waitTime));
              continue;
            }
            throw error;
        }
      }
      throw error;
    }
  }
  
  throw new Error('Max retries exceeded');
}

// Usage
try {
  const result = await robustSearch('AI developments');
  console.log(result.summary);
} catch (error) {
  console.error(`Error: ${error.code} - ${error.message}`);
  if (error.suggestion) {
    console.log(`Suggestion: ${error.suggestion}`);
  }
}

cURL Error Handling

#!/bin/bash

# Function to make API request with retries
make_request() {
    local query="$1"
    local max_retries=3
    local attempt=1
    
    while [ $attempt -le $max_retries ]; do
        response=$(curl -s -w "%{http_code}" \
            -X POST https://api.usecortex.co/v1/search \
            -H "Authorization: Bearer $API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"query\": \"$query\"}")
        
        http_code="${response: -3}"
        body="${response%???}"
        
        case $http_code in
            200)
                echo "$body" | jq '.'
                return 0
                ;;
            429)
                retry_after=$(echo "$body" | jq -r '.error.details.retry_after // 60')
                echo "Rate limited, waiting ${retry_after}s..."
                sleep $retry_after
                ;;
            5*)
                wait_time=$((2 ** (attempt - 1)))
                echo "Server error, waiting ${wait_time}s..."
                sleep $wait_time
                ;;
            *)
                echo "Error: $body" | jq '.'
                return 1
                ;;
        esac
        
        ((attempt++))
    done
    
    echo "Max retries exceeded"
    return 1
}

# Usage
make_request "AI developments"

📊 Error Monitoring

Track Error Patterns

# Monitor error rates
error_stats = client.monitoring.errors(period="day")

if error_stats.error_rate > 0.05:  # 5% error rate
    print(f"High error rate detected: {error_stats.error_rate:.2%}")
    
    # Check most common errors
    for error in error_stats.error_breakdown:
        if error.count > 10:
            print(f"Frequent error: {error.error_code} ({error.count} times)")

Set Up Alerts

Monitor for:

• Error rate > 5%
• Specific error codes (TIMEOUT, RATE_LIMITED)
• Server errors (5xx status codes)
• Authentication failures

🆘 Getting Help

When contacting support, include:

• Request ID from error response
• Full error response (JSON)
• Code sample that triggered the error
• Expected behavior vs actual behavior
• API key (last 4 characters only)

Support channels:

• Email: help@usecortex.co
• Discord: discord.gg/cortex
• Status: status.usecortex.co

---

Next: Python SDK → - Official Python library