Skip to main content
All Cortex API endpoints follow a consistent error response format. This page documents the standard HTTP error codes and their corresponding response structures.

​
Standard Error Response Format

All error responses follow this consistent structure: 
{
  "detail": {
    "success": false,
    "message": "Error description",
    "error_code": "SPECIFIC_ERROR_CODE"
  }
}

​
HTTP Status Codes

​
400 Bad Request

When it occurs: Invalid input parameters, malformed requests, or validation failures. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Invalid request parameters",
    "error_code": "INVALID_PARAMETERS"
  }
}
Common scenarios:
  • Missing required parameters
  • Invalid parameter formats
  • Malformed JSON in request body
  • Invalid file formats
  • Attempting to delete default sub-tenant

​
401 Unauthorized

When it occurs: Invalid or missing API key, authentication required. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Authentication required",
    "error_code": "UNAUTHORIZED"
  }
}
Common scenarios:
  • Missing API key in headers
  • Invalid API key
  • Expired API key
  • Insufficient permissions

​
403 Forbidden

When it occurs: Valid authentication but insufficient permissions for the requested resource. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Access denied",
    "error_code": "FORBIDDEN"
  }
}
Common scenarios:
  • API key lacks required permissions
  • Tenant access restrictions
  • Resource ownership conflicts

​
404 Not Found

When it occurs: Requested resource does not exist. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Resource not found",
    "error_code": "NOT_FOUND"
  }
}
Common scenarios:
  • Tenant does not exist
  • Sub-tenant does not exist
  • File/document not found
  • User memory not found
  • Source not found

​
409 Conflict

When it occurs: Resource already exists or conflicts with existing data. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Resource already exists",
    "error_code": "CONFLICT"
  }
}
Common scenarios:
  • Tenant ID already exists
  • Duplicate file uploads
  • Conflicting metadata schemas

​
422 Unprocessable Entity

When it occurs: Request is well-formed but contains semantic errors. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Validation failed",
    "error_code": "VALIDATION_ERROR"
  }
}
Common scenarios:
  • Invalid metadata schema
  • Content validation failures
  • Business rule violations
  • Data format incompatibilities

​
500 Internal Server Error

When it occurs: Unexpected server-side error. Example Response: 
{
  "detail": {
    "success": false,
    "message": "Internal server error",
    "error_code": "INTERNAL_ERROR"
  }
}
Error Handling: Always check the detail object in error responses for the actual error information. The outer structure may vary, but the detail object always follows the standard format.
Common scenarios:
  • Database connectivity issues
  • Processing pipeline failures
  • External service unavailability
  • System resource constraints

​
Endpoint-Specific Error Codes

​
Tenant Management

  • TENANT_ALREADY_EXISTS: Tenant ID is already in use
  • TENANT_NOT_FOUND: Specified tenant does not exist
  • INVALID_TENANT_ID: Tenant ID format is invalid

​
Sub-Tenant Management

  • CANNOT_DELETE_DEFAULT_SUB_TENANT: Attempting to delete the default sub-tenant
  • SUB_TENANT_NOT_FOUND: Specified sub-tenant does not exist
  • INVALID_SUB_TENANT_ID: Sub-tenant ID format is invalid

​
Document Management

  • FILE_NOT_FOUND: Requested file does not exist
  • INVALID_FILE_FORMAT: Unsupported file format
  • FILE_TOO_LARGE: File exceeds size limits
  • PROCESSING_FAILED: Document processing encountered an error

​
Search Operations

  • INVALID_SEARCH_PARAMETERS: Search query parameters are invalid
  • SEARCH_TIMEOUT: Search operation timed out
  • NO_RESULTS_FOUND: No matching results for the search query

​
User Memory

  • MEMORY_NOT_FOUND: User memory does not exist
  • MEMORY_LIMIT_EXCEEDED: User has reached memory storage limit
  • INVALID_MEMORY_FORMAT: Memory content format is invalid

​
Embeddings

  • EMBEDDINGS_NOT_FOUND: Requested embeddings do not exist
  • INVALID_EMBEDDING_FORMAT: Embedding data format is invalid
  • EMBEDDING_GENERATION_FAILED: Failed to generate embeddings

​
Error Handling Best Practices

​
Client-Side Error Handling

try {
  const response = await fetch('/api/endpoint', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(requestData)
  });

  if (!response.ok) {
    const errorData = await response.json();
    console.error(`Error ${response.status}: ${errorData.detail.message}`);
    
    // Handle specific error codes
    switch (errorData.detail.error_code) {
      case 'TENANT_NOT_FOUND':
        // Handle tenant not found
        break;
      case 'UNAUTHORIZED':
        // Handle authentication error
        break;
      default:
        // Handle generic error
        break;
    }
  }
} catch (error) {
  console.error('Network error:', error);
}

​
Retry Logic

For transient errors (5xx), implement exponential backoff: 
async function retryRequest(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      if (response.ok || response.status < 500) {
        return response;
      }
      
      if (attempt === maxRetries) {
        throw new Error(`Request failed after ${maxRetries} attempts`);
      }
      
      // Exponential backoff
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, attempt) * 1000)
      );
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
}

​
Troubleshooting Common Issues

​
Authentication Issues

  1. Check API Key: Ensure your API key is valid and not expired
  2. Header Format: Verify the Authorization header format: Bearer YOUR_API_KEY
  3. Permissions: Confirm your API key has the required permissions

​
Resource Not Found

  1. Verify IDs: Double-check tenant_id, sub_tenant_id, and file_id values
  2. Case Sensitivity: Ensure IDs match exactly (case-sensitive)
  3. Existence: Confirm the resource exists before making requests

​
Validation Errors

  1. Required Fields: Ensure all required parameters are provided
  2. Data Types: Verify parameter types match the expected format
  3. File Formats: Check that uploaded files are in supported formats

​
Rate Limiting

  1. Request Frequency: Reduce the frequency of API calls
  2. Batch Operations: Use batch endpoints when available
  3. Caching: Implement client-side caching for frequently accessed data
Error Code Consistency: All error codes follow a consistent naming convention using UPPER_SNAKE_CASE. This makes it easy to programmatically handle specific error scenarios in your application.
Error Response Structure: Always check the detail object in error responses, as this contains the actual error information. The outer structure may vary, but the detail object always follows the standard format.
⌘I