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 TypeCommon CauseSolution
NotFoundErrorResource ID doesn’t exist or was deletedVerify IDs and check if the resource was deleted
ValidationErrorInvalid data format or missing required fieldsCheck the API documentation for required fields and formats
TooManyRequestsErrorRate limit exceededImplement backoff with the provided retry_after value
FeatureExtractionErrorContent format issue or corrupted fileVerify file integrity and ensure it matches supported formats
MimeTypeErrorUnsupported file typeConvert to a supported format listed in the docs
S3StorageErrorNetwork issues or file size too largeCheck network connection and file size limits
TimeoutErrorOperation took too long to completeBreak large operations into smaller batches

​
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.)

​
Processing Errors

​
Content Format and Validation Errors

Errors related to invalid input data or format issues:
Error CodeDescriptionResolution
INVALID_FORMATFile format not supported or corruptedVerify file is in a supported format and not corrupted
SCHEMA_VALIDATIONObject does not match bucket schemaCheck object structure against bucket schema requirements
EXCEEDED_SIZEFile size exceeds allowed maximumReduce file size or request increased limits
MALFORMED_JSONInvalid JSON structure in metadata or configValidate JSON structure before submission
MISSING_REQUIREDRequired field or property is missingAdd all required properties to the request payload

​
Storage Errors

​
Raw Data Storage Issues

Errors related to bucket operations and object storage:
Error CodeDescriptionResolution
BUCKET_NOT_FOUNDReferenced bucket does not existVerify bucket ID or create the bucket
OBJECT_NOT_FOUNDReferenced object does not existCheck object ID and bucket path
DUPLICATE_OBJECTObject with same ID already existsUse unique object IDs or update existing object
BLOB_UPLOAD_FAILEDFailed to upload blob to storageCheck network connection and retry
PREFIX_INVALIDObject prefix format is invalidUse valid path format for prefix

​
Database Errors

Errors related to database operations.

​
Qdrant Vector Database Issues

Errors related to vector database operations:
Error CodeDescriptionResolution
VECTOR_INSERT_FAILEDFailed to insert vectors into databaseCheck vector format and dimensions
INDEX_CREATION_FAILEDFailed to create search indexVerify index configuration parameters
INVALID_VECTOR_DIMENSIONVector dimensions don’t match configured spaceEnsure vectors match the expected dimension count
VECTOR_QUERY_FAILEDSearch query operation failedCheck query syntax and parameters
COLLECTION_CONFIG_ERRORVector collection configuration issueReview collection settings and recreate if needed
{
  "success": false,
  "status": 500,
  "error": {
    "message": "Vector database operation failed",
    "type": "QdrantDatabaseError"
  }
}

​
Workflow Errors

Errors related to workflow orchestration and pipeline execution.

​
Data Processing Pipeline Issues

Errors related to pipeline execution and processing:
Error CodeDescriptionResolution
PIPELINE_CONFIG_INVALIDInvalid pipeline configurationCheck pipeline configuration syntax and components
STAGE_EXECUTION_FAILEDSpecific pipeline stage failedReview logs for the failing stage
INPUT_VALIDATION_FAILEDPipeline input validation errorEnsure inputs match pipeline requirements
PIPELINE_TIMEOUTPipeline execution timed outOptimize processing or break into smaller pipelines
DEPENDENCY_MISSINGRequired pipeline dependency not foundInstall 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

​
Contacting Support

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

Developer Community

Ask questions in our community forum