Skip to main content

​
API Error Format

All errors return a consistent envelope: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "bucket_schema.properties is required",
    "details": {}
  }
}

​
Common Errors

CodeStatusCauseFix
VALIDATION_ERROR422Missing or invalid fieldsCheck required fields in the API reference
UNAUTHORIZED401Invalid or missing API keyVerify Authorization: Bearer sk_live_... header
FORBIDDEN403Namespace mismatch or insufficient permissionsCheck X-Namespace header matches the resource
NOT_FOUND404Resource doesn’t existVerify the ID and namespace
RATE_LIMIT_EXCEEDED429Too many requestsBack off and retry with exponential delay
TASK_FAILED500Processing error in engineCheck task details for the specific failure reason

​
Rate Limits

TierRequests/minConcurrent tasks
Free605
Pro60050
EnterpriseCustomCustom
When you hit a 429, the response includes Retry-After header with seconds to wait.

​
Debugging Checklist

​
Objects not processing

  1. Check batch status: GET /v1/buckets/{bucket_id}/batches/{batch_id}
  2. Check task status: GET /v1/tasks/{task_id}
  3. Verify the collection’s feature_extractor matches the bucket schema’s blob types
  4. Check for failed documents: GET /v1/buckets/{bucket_id}/batches/{batch_id}/failed

​
Retriever returning zero results

  1. Verify documents exist: POST /v1/collections/{collection_id}/documents/list
  2. Check the feature_uri in your stage matches the collection’s extractor output
  3. Try a broader query or lower the similarity threshold
  4. Use the explain endpoint to see the execution plan

​
Poor retrieval quality

  1. Check if the right extractor is being used for your query type (text query → text embedding, image query → visual embedding)
  2. Add a reranking stage to improve precision
  3. Review the execution trace for score distributions
  4. Consider adding more retriever stages (filters, MMR for diversity)

​
Slow processing

  1. Video processing time scales with duration — 1 min video ≈ 1-2 min processing
  2. Use batch processing for bulk imports instead of single-object ingestion
  3. Check for resource contention: GET /v1/tasks?status=PROCESSING

​
FAQ

Can I use multiple feature extractors on the same data? Yes — create multiple collections pointing to the same bucket, each with a different extractor. How do I re-process documents after changing a collection’s extractor? Create a new batch with the same objects and submit it. New documents replace old ones. What file formats are supported? Video (MP4, MOV, AVI, WebM), Images (JPG, PNG, WebP, GIF), Audio (MP3, WAV, M4A, FLAC), Documents (PDF, DOCX, TXT, HTML). How do I delete all data in a namespace? Delete the namespace: DELETE /v1/namespaces/{namespace_id}. This removes all buckets, collections, retrievers, and documents. Is there a size limit for uploads? Default: 500MB per file. Enterprise plans support larger files. Use URL references for files already in cloud storage. Contact support →