Error Responses

Comprehensive guide to HTTP error responses and their meanings across all Cortex API endpoints

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.