Errors

This page documents the various error types you may encounter when working with the Mixpeek API, and provides guidance on how to handle and resolve them.

Error Response Format

All Mixpeek API errors follow a consistent JSON response format:

{
  "success": false,
  "status": 400,
  "error": {
    "message": "The error message with details",
    "type": "ErrorType",
    "details": {
      // Additional error-specific information (optional)
    }
  }
}

Common Errors and Solutions

Error Type	Common Cause	Solution
NotFoundError	Resource ID doesn’t exist or was deleted	Verify IDs and check if the resource was deleted
ValidationError	Invalid data format or missing required fields	Check the API documentation for required fields and formats
TooManyRequestsError	Rate limit exceeded	Implement backoff with the provided retry_after value
FeatureExtractionError	Content format issue or corrupted file	Verify file integrity and ensure it matches supported formats
MimeTypeError	Unsupported file type	Convert to a supported format listed in the docs
S3StorageError	Network issues or file size too large	Check network connection and file size limits
TimeoutError	Operation took too long to complete	Break large operations into smaller batches

Field	Description
`success`	Always `false` for error responses
`status`	HTTP status code
`error.message`	Human-readable error description
`error.type`	Error type identifier
`error.details`	Additional information about the error (optional)

Status Code	Description
400	Bad Request - The request was malformed or invalid
401	Unauthorized - Authentication is required or failed
403	Forbidden - You don’t have permission to access the resource
404	Not Found - The requested resource doesn’t exist
409	Conflict - The request conflicts with the current state
422	Validation Error - The request contained invalid data
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error
503	Service Unavailable - The service is temporarily unavailable

HTTP Errors

These errors represent standard HTTP status code errors.

{
  "success": false,
  "status": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "BadRequestError"
  }
}

Common Causes:

Missing required fields
Invalid parameter formats
Logical errors in the request

Resolution:

Check your request payload against the API documentation
Ensure all required fields are included
Verify parameter formats (IDs, dates, etc.)

{
  "success": false,
  "status": 400,
  "error": {
    "message": "Invalid request parameters",
    "type": "BadRequestError"
  }
}

Common Causes:

Missing required fields
Invalid parameter formats
Logical errors in the request

Resolution:

Check your request payload against the API documentation
Ensure all required fields are included
Verify parameter formats (IDs, dates, etc.)

{
  "success": false,
  "status": 404,
  "error": {
    "message": "Resource not found",
    "type": "NotFoundError",
    "details": {
      "resource_type": "Document",
      "resource_id": "doc_12345"
    }
  }
}

Common Causes:

Incorrect ID or resource identifier
Resource has been deleted
Resource exists in a different namespace

Resolution:

Verify the resource ID exists
Check namespace and context
Ensure the resource hasn’t been deleted

{
  "success": false,
  "status": 409,
  "error": {
    "message": "Resource already exists",
    "type": "AlreadyExistsError",
    "details": {
      "resource_type": "Collection",
      "resource_id": "collection_12345"
    }
  }
}

Common Causes:

Attempting to create a resource with a name/ID that already exists
Race conditions when creating resources

Resolution:

Use unique identifiers for new resources
Implement idempotent creation methods
Check if the resource exists before creating it

{
  "success": false,
  "status": 429,
  "error": {
    "message": "Rate limit exceeded. Please retry after 35 seconds.",
    "type": "TooManyRequestsError",
    "details": {
      "retry_after": 35
    }
  }
}

Common Causes:

Exceeding API rate limits
Too many concurrent requests

Resolution:

Implement exponential backoff
Check the retry_after value in the response
Consider upgrading your plan for higher limits

Processing Errors

Content Format and Validation Errors

Errors related to invalid input data or format issues:

Error Code	Description	Resolution
`INVALID_FORMAT`	File format not supported or corrupted	Verify file is in a supported format and not corrupted
`SCHEMA_VALIDATION`	Object does not match bucket schema	Check object structure against bucket schema requirements
`EXCEEDED_SIZE`	File size exceeds allowed maximum	Reduce file size or request increased limits
`MALFORMED_JSON`	Invalid JSON structure in metadata or config	Validate JSON structure before submission
`MISSING_REQUIRED`	Required field or property is missing	Add all required properties to the request payload

Content Format and Validation Errors

Errors related to invalid input data or format issues:

Error Code	Description	Resolution
`INVALID_FORMAT`	File format not supported or corrupted	Verify file is in a supported format and not corrupted
`SCHEMA_VALIDATION`	Object does not match bucket schema	Check object structure against bucket schema requirements
`EXCEEDED_SIZE`	File size exceeds allowed maximum	Reduce file size or request increased limits
`MALFORMED_JSON`	Invalid JSON structure in metadata or config	Validate JSON structure before submission
`MISSING_REQUIRED`	Required field or property is missing	Add all required properties to the request payload

Feature Extraction Failures

Errors occurring during feature extraction processing:

Error Code	Description	Resolution
`EXTRACTION_TIMEOUT`	Feature extraction exceeded time limit	Optimize input file or increase timeout threshold
`MODEL_UNAVAILABLE`	Required extraction model unavailable	Try again later or contact support
`UNSUPPORTED_CONTENT`	Content type not supported by extractor	Verify compatibility between content and extractor
`EXTRACTION_FAILED`	General extraction failure	Check logs for specific error details
`INSUFFICIENT_CONTENT`	Content too small or lacks necessary information	Ensure content meets minimum requirements for extraction

Resource and Capacity Limitations

Errors related to system resources and limitations:

Error Code	Description	Resolution
`QUOTA_EXCEEDED`	Account quota or rate limit exceeded	Reduce request rate or upgrade account tier
`INSUFFICIENT_STORAGE`	Not enough storage in namespace	Free up storage or request increased capacity
`PROCESSING_CAPACITY`	System processing capacity reached	Retry during lower usage period
`MEMORY_LIMIT`	Operation exceeded memory limits	Optimize request or split into smaller operations
`CONCURRENT_LIMIT`	Too many concurrent operations	Reduce number of parallel processes

Internal System Failures

Errors related to internal system issues:

Error Code	Description	Resolution
`INTERNAL_ERROR`	Unexpected system error	Contact support with error details
`SERVICE_UNAVAILABLE`	Processing service temporarily unavailable	Retry operation after a short delay
`DATABASE_ERROR`	Error connecting to storage backend	Check system status or contact support
`DEPENDENCY_FAILURE`	External service dependency failure	Verify third-party service status
`INCONSISTENT_STATE`	System detected inconsistent data state	Contact support for data recovery options

Setup and Configuration Issues

Errors related to pipeline and configuration settings:

Error Code	Description	Resolution
`INVALID_PIPELINE`	Pipeline configuration is invalid	Review and correct pipeline definition
`MISSING_PARAMETER`	Required configuration parameter missing	Add all required parameters to configuration
`INCOMPATIBLE_COMPONENTS`	Pipeline components are incompatible	Verify compatibility between pipeline stages
`CIRCULAR_REFERENCE`	Circular dependency in configuration	Restructure pipeline to remove circular references
`FEATURE_CONFLICT`	Conflicting feature extractors specified	Remove conflicting components from pipeline

Storage Errors

Raw Data Storage Issues

Errors related to bucket operations and object storage:

Error Code	Description	Resolution
`BUCKET_NOT_FOUND`	Referenced bucket does not exist	Verify bucket ID or create the bucket
`OBJECT_NOT_FOUND`	Referenced object does not exist	Check object ID and bucket path
`DUPLICATE_OBJECT`	Object with same ID already exists	Use unique object IDs or update existing object
`BLOB_UPLOAD_FAILED`	Failed to upload blob to storage	Check network connection and retry
`PREFIX_INVALID`	Object prefix format is invalid	Use valid path format for prefix

Raw Data Storage Issues

Errors related to bucket operations and object storage:

Error Code	Description	Resolution
`BUCKET_NOT_FOUND`	Referenced bucket does not exist	Verify bucket ID or create the bucket
`OBJECT_NOT_FOUND`	Referenced object does not exist	Check object ID and bucket path
`DUPLICATE_OBJECT`	Object with same ID already exists	Use unique object IDs or update existing object
`BLOB_UPLOAD_FAILED`	Failed to upload blob to storage	Check network connection and retry
`PREFIX_INVALID`	Object prefix format is invalid	Use valid path format for prefix

Document Storage Issues

Errors related to collection operations and document storage:

Error Code	Description	Resolution
`COLLECTION_NOT_FOUND`	Referenced collection does not exist	Verify collection ID or create the collection
`DOCUMENT_NOT_FOUND`	Referenced document does not exist	Check document ID and collection
`SCHEMA_MISMATCH`	Document does not match collection schema	Update document to match collection schema
`INDEX_CONSTRAINT`	Document violates index constraints	Modify document to comply with index requirements
`DOCUMENT_TOO_LARGE`	Document exceeds size limits	Reduce document size or split into multiple documents

Feature Store Issues

Errors related to feature storage operations:

Error Code	Description	Resolution
`VECTOR_STORE_ERROR`	Error accessing vector storage	Check vector store connection and configuration
`INVALID_EMBEDDING`	Embedding format or dimensions invalid	Verify embedding dimensions match configured vector store
`FEATURE_NOT_FOUND`	Referenced feature does not exist	Check feature ID and document reference
`INDEX_BUILD_FAILED`	Failed to build vector index	Check index configuration and available resources
`VECTOR_LIMIT_EXCEEDED`	Exceeded vector count limit for store	Reduce number of vectors or upgrade storage tier

Access and Permission Errors

Errors related to storage access permissions:

Error Code	Description	Resolution
`ACCESS_DENIED`	Insufficient permissions for operation	Verify API key has required permissions
`NAMESPACE_ACCESS`	Cannot access specified namespace	Ensure account has access to the namespace
`READ_ONLY_ACCESS`	Attempted write to read-only resource	Use appropriate credentials with write access
`OWNERSHIP_REQUIRED`	Operation requires resource ownership	Transfer ownership or use owner credentials
`KEY_SCOPE_LIMITED`	API key scope does not include action	Create new API key with required scope

Storage Lifecycle Management

Errors related to storage management and organization:

Error Code	Description	Resolution
`STORAGE_QUOTA_EXCEEDED`	Namespace storage quota exceeded	Free up storage or request increased quota
`RETENTION_POLICY_CONFLICT`	Operation conflicts with retention policy	Modify operation to comply with retention policy
`VERSIONING_ERROR`	Error in object versioning	Check versioning configuration
`LIFECYCLE_RULE_ERROR`	Lifecycle management rule error	Review and correct lifecycle rules
`REPLICATION_FAILED`	Data replication between regions failed	Check replication configuration and network

Database Errors

Errors related to database operations.

Qdrant Vector Database Issues

Errors related to vector database operations:

Error Code	Description	Resolution
`VECTOR_INSERT_FAILED`	Failed to insert vectors into database	Check vector format and dimensions
`INDEX_CREATION_FAILED`	Failed to create search index	Verify index configuration parameters
`INVALID_VECTOR_DIMENSION`	Vector dimensions don’t match configured space	Ensure vectors match the expected dimension count
`VECTOR_QUERY_FAILED`	Search query operation failed	Check query syntax and parameters
`COLLECTION_CONFIG_ERROR`	Vector collection configuration issue	Review collection settings and recreate if needed

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Vector database operation failed",
    "type": "QdrantDatabaseError"
  }
}

Qdrant Vector Database Issues

Errors related to vector database operations:

Error Code	Description	Resolution
`VECTOR_INSERT_FAILED`	Failed to insert vectors into database	Check vector format and dimensions
`INDEX_CREATION_FAILED`	Failed to create search index	Verify index configuration parameters
`INVALID_VECTOR_DIMENSION`	Vector dimensions don’t match configured space	Ensure vectors match the expected dimension count
`VECTOR_QUERY_FAILED`	Search query operation failed	Check query syntax and parameters
`COLLECTION_CONFIG_ERROR`	Vector collection configuration issue	Review collection settings and recreate if needed

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Vector database operation failed",
    "type": "QdrantDatabaseError"
  }
}

MongoDB Document Storage Issues

Errors related to document database operations:

Error Code	Description	Resolution
`DOCUMENT_INSERT_FAILED`	Failed to insert document into database	Check document format and required fields
`QUERY_SYNTAX_ERROR`	Invalid query syntax	Verify query structure follows MongoDB syntax
`INDEX_MISSING`	Required index not found	Create necessary indexes for query performance
`DUPLICATE_KEY`	Document with same unique key exists	Use upsert or check for existing documents
`CONNECTION_ERROR`	Database connection issue	Check network and database availability

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Failed to query MongoDB",
    "type": "DatabaseError"
  }
}

Database Write Failures

Errors related to writing data to storage systems:

Error Code	Description	Resolution
`TRANSACTION_FAILED`	Database transaction failure	Retry operation or check data consistency
`WRITE_TIMEOUT`	Write operation timed out	Check database performance and try smaller batches
`CONCURRENT_MODIFICATION`	Document modified concurrently	Implement optimistic concurrency control
`SCHEMA_VIOLATION`	Data violates schema constraints	Modify data to match required schema
`PERMISSION_ERROR`	Insufficient write permissions	Check database user permissions

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Failed to write document to database",
    "type": "DBWriterError"
  }
}

Workflow Errors

Errors related to workflow orchestration and pipeline execution.

Data Processing Pipeline Issues

Errors related to pipeline execution and processing:

Error Code	Description	Resolution
`PIPELINE_CONFIG_INVALID`	Invalid pipeline configuration	Check pipeline configuration syntax and components
`STAGE_EXECUTION_FAILED`	Specific pipeline stage failed	Review logs for the failing stage
`INPUT_VALIDATION_FAILED`	Pipeline input validation error	Ensure inputs match pipeline requirements
`PIPELINE_TIMEOUT`	Pipeline execution timed out	Optimize processing or break into smaller pipelines
`DEPENDENCY_MISSING`	Required pipeline dependency not found	Install or configure missing dependencies

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Pipeline processing error",
    "type": "PipelineError",
    "details": {
      "pipeline_id": "pipeline_12345"
    }
  }
}

Resolution:

Check pipeline configuration
Review task logs for specific failure points
Verify input data meets pipeline requirements

Data Processing Pipeline Issues

Errors related to pipeline execution and processing:

Error Code	Description	Resolution
`PIPELINE_CONFIG_INVALID`	Invalid pipeline configuration	Check pipeline configuration syntax and components
`STAGE_EXECUTION_FAILED`	Specific pipeline stage failed	Review logs for the failing stage
`INPUT_VALIDATION_FAILED`	Pipeline input validation error	Ensure inputs match pipeline requirements
`PIPELINE_TIMEOUT`	Pipeline execution timed out	Optimize processing or break into smaller pipelines
`DEPENDENCY_MISSING`	Required pipeline dependency not found	Install or configure missing dependencies

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Pipeline processing error",
    "type": "PipelineError",
    "details": {
      "pipeline_id": "pipeline_12345"
    }
  }
}

Resolution:

Check pipeline configuration
Review task logs for specific failure points
Verify input data meets pipeline requirements

Workflow Orchestration Issues

Errors related to workflow scheduling and management:

Error Code	Description	Resolution
`FLOW_EXECUTION_FAILED`	Workflow execution failure	Check workflow logs and task dependencies
`TASK_DEPENDENCY_ERROR`	Task dependency resolution failed	Verify task dependency configuration
`SCHEDULING_ERROR`	Workflow scheduling error	Check schedule configuration and triggers
`RESOURCE_ALLOCATION_FAILED`	Failed to allocate required resources	Verify resource availability and requirements
`STATE_PERSISTENCE_ERROR`	Error saving workflow state	Check storage system for workflow states

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Workflow orchestration error",
    "type": "PrefectError",
    "details": {
      "flow_id": "flow_12345"
    }
  }
}

Resolution:

Check for service disruptions
Verify workflow configuration
Review task dependencies

Task Execution Issues

Errors related to individual task execution:

Error Code	Description	Resolution
`TASK_TIMEOUT`	Task execution timed out	Optimize task or increase timeout
`RESOURCE_EXHAUSTED`	Task exceeded allocated resources	Optimize resource usage or increase allocation
`TASK_RETRY_FAILED`	Task failed after maximum retries	Investigate persistent failure cause
`INPUT_SERIALIZATION_ERROR`	Error serializing task inputs	Check input data format and size
`OUTPUT_HANDLING_ERROR`	Error processing task outputs	Verify output handlers and data structure

{
  "success": false,
  "status": 500,
  "error": {
    "message": "Task execution failed after 3 retries",
    "type": "TaskExecutionError",
    "details": {
      "task_id": "task_67890",
      "retries": 3
    }
  }
}

Contacting Support

If you encounter persistent errors or need help troubleshooting specific issues, contact our support team with the following information:

Email Support

Send details to support@mixpeek.com

Developer Community

Ask questions in our community forum

Email Support

Overview

Data Management

Data Processing

Search & Retrieval

Data Enrichment

Troubleshooting

Error Response Format

Common Errors and Solutions

HTTP Errors

Processing Errors

Content Format and Validation Errors

Content Format and Validation Errors

Feature Extraction Failures

Resource and Capacity Limitations

Internal System Failures

Setup and Configuration Issues

Storage Errors

Raw Data Storage Issues

Raw Data Storage Issues

Document Storage Issues

Feature Store Issues

Access and Permission Errors

Storage Lifecycle Management

Database Errors

Qdrant Vector Database Issues

Qdrant Vector Database Issues

MongoDB Document Storage Issues

Database Write Failures

Workflow Errors

Data Processing Pipeline Issues

Data Processing Pipeline Issues

Workflow Orchestration Issues

Task Execution Issues

Contacting Support

Developer Community

Overview

Data Management

Data Processing

Search & Retrieval

Data Enrichment

Troubleshooting

​Error Response Format

​Common Errors and Solutions

​HTTP Errors

​Processing Errors

​Content Format and Validation Errors

​Content Format and Validation Errors

​Feature Extraction Failures

​Resource and Capacity Limitations

​Internal System Failures

​Setup and Configuration Issues

​Storage Errors

​Raw Data Storage Issues

​Raw Data Storage Issues

​Document Storage Issues

​Feature Store Issues

​Access and Permission Errors

​Storage Lifecycle Management

​Database Errors

​Qdrant Vector Database Issues

​Qdrant Vector Database Issues

​MongoDB Document Storage Issues

​Database Write Failures

​Workflow Errors

​Data Processing Pipeline Issues

​Data Processing Pipeline Issues

​Workflow Orchestration Issues

​Task Execution Issues

​Contacting Support

Email Support

Developer Community

Error Response Format

Common Errors and Solutions

HTTP Errors

Processing Errors

Content Format and Validation Errors

Content Format and Validation Errors

Feature Extraction Failures

Resource and Capacity Limitations

Internal System Failures

Setup and Configuration Issues

Storage Errors

Raw Data Storage Issues

Raw Data Storage Issues

Document Storage Issues

Feature Store Issues

Access and Permission Errors

Storage Lifecycle Management

Database Errors

Qdrant Vector Database Issues

Qdrant Vector Database Issues

MongoDB Document Storage Issues

Database Write Failures

Workflow Errors

Data Processing Pipeline Issues

Data Processing Pipeline Issues

Workflow Orchestration Issues

Task Execution Issues

Contacting Support